‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

אימות בקשות מ-Google Chat

בקטע הזה מוסבר איך לוודא שבקשות לנקודות קצה (endpoints) של HTTP, שעליהן מבוססות אפליקציות ל-Google Chat, מגיעות מ-Chat.

כדי לשלוח אירועים של אינטראקציות לנקודת הקצה של אפליקציית Chat, ‏ Google יוצרת בקשות HTTPS לשירות שלכם. כדי לוודא שהבקשה מגיעה מ-Google, ‏ Chat כולל טוקן של מזהה של OpenID Connect ‏ (OIDC) בחתימת Google כטוקן למוכ"ז בכותרת Authorization של כל בקשת HTTPS (ובשדה authorizationEventObject.systemIdToken של גוף הבקשה). לדוגמה:

POST
Host: yourappurl.com
Authorization: Bearer AbCdEf123456
Content-Type: application/json
User-Agent: Google-Dynamite

המחרוזת AbCdEf123456 בדוגמה הקודמת היא טוקן הרשאת הגישה. האסימון הקריפטוגרפי הזה חתום על ידי חשבון השירות הייחודי של אפליקציית Chat לכל פרויקט (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com), והשדה audience מוגדר לכתובת ה-URL של נקודת הקצה מסוג HTTP שהוגדרה לאפליקציית Chat כשמגדירים את אפליקציית Chat.

אפשר להעתיק את כתובת האימייל של חשבון השירות של אפליקציית Chat מהקטע Connection settings בכרטיסייה Configuration של Chat API במסוף Google Cloud:

במסוף Google Cloud, לוחצים על תפריט > APIs & Services > Enabled APIs & Services > Google Chat API > Configuration:

מעבר אל Google Chat API Configuration
בקטע תכונות אינטראקטיביות > הגדרות חיבור, מעתיקים את האימייל של חשבון השירות (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com).

אם הטמעתם את אפליקציית Chat באמצעות פונקציות Cloud Run או Cloud Run, מערכת Cloud IAM מטפלת באימות האסימון באופן אוטומטי כשאתם מעניקים לחשבון השירות של אפליקציית Chat את התפקיד Cloud Run Invoker (roles/run.invoker). אם האפליקציה שלכם מטמיעה שרת HTTP משלה, אתם יכולים לאמת את אסימון ה-Bearer באמצעות ספריית לקוח של Google API בקוד פתוח:

‫Java: ‏ https://github.com/google/google-api-java-client
‫Python: https://github.com/google/google-api-python-client
‫Node.js: https://github.com/google/google-api-nodejs-client
‫.NET: https://github.com/google/google-api-dotnet-client

אם אי אפשר לאמת את הטוקן באפליקציית Chat, השירות שלכם צריך להשיב לבקשה עם קוד תגובה של HTTPS‏ 401 (Unauthorized).

אימות בקשות באמצעות פונקציות Cloud Run

אם הלוגיקה של הפונקציה מיושמת באמצעות פונקציות Cloud Run או Cloud Run, צריך לוודא שכתובות ה-URL של נקודות הקצה של HTTP שהוגדרו בקטע Triggers בהגדרות החיבור של אפליקציית Chat תואמות לכתובת ה-URL של נקודת הקצה של פונקציית Cloud Run.

לאחר מכן, מאשרים את חשבון השירות של אפליקציית Chat (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com, שהועתק מהקטע Connection settings בכרטיסייה Configuration של Chat API) כגורם מפעיל באמצעות השלבים הבאים:

המסוף

אחרי שפורסים את הפונקציה או השירות ב-Google Cloud:

במסוף Google Cloud, עוברים לדף Cloud Run:

כניסה ל-Cloud Run
ברשימת שירותי Cloud Run, לוחצים על תיבת הסימון לצד הפונקציה המקבלת. (לא לוחצים על הפונקציה עצמה).
לוחצים על הרשאות בחלק העליון של המסך. נפתח החלונית הרשאות.
לוחצים על Add principal.
בשדה New principals, מזינים את כתובת האימייל של חשבון השירות של אפליקציית Chat (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com).
בתפריט Select a role (בחירת תפקיד), בוחרים בתפקיד Cloud Run.

‫Cloud Run Invoker.
לוחצים על שמירה.

gcloud

משתמשים בפקודה gcloud functions add-invoker-policy-binding:

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:service-PROJECT_NUMBER@gcp-sa-gsuiteaddons.iam.gserviceaccount.com'

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

‫RECEIVING_FUNCTION: השם של הפונקציה של אפליקציית Chat.
‫PROJECT_NUMBER: מספר הפרויקט מכתובת האימייל של חשבון השירות של אפליקציית Chat.

אימות בקשות HTTP באמצעות טוקן של מזהה

בנקודות קצה של HTTP, אסימון ההרשאה מסוג bearer בבקשה הוא טוקן של מזהה של OpenID Connect ‏ (OIDC) בחתימת Google. השדה email מוגדר לכתובת האימייל של חשבון השירות של אפליקציית Chat‏ (service-<var>PROJECT_NUMBER</var>@gcp-sa-gsuiteaddons.iam.gserviceaccount.com), והשדה audience מוגדר לכתובת ה-URL של נקודת הקצה של ה-HTTP שהוגדרה לקבלת הבקשה. לדוגמה, אם נקודת הקצה המוגדרת של אפליקציית Chat היא https://example.com/app/, אז השדה audience בטוקן של מזהה הוא https://example.com/app/.

זוהי שיטת האימות המומלצת אם נקודת הקצה של ה-HTTP לא מתארחת בשירות שתומך באימות מבוסס-IAM (כמו Cloud Run).

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

Java

java/chat/secured-app/src/main/java/com/google/chat/app/secured/App.java

הצגת הקוד ב-GitHub

/**
 * Determine whether a Google Workspace add-on request is legitimate.
 * 
 * @param event Event sent from Google Workspace add-on
 * @param authorization Authorization header from the request
 * @return {boolean} Whether the request is legitimate
 */
private boolean verifyAddOnRequest(JsonNode event, String authorization) throws Exception {
  JsonFactory factory = JacksonFactory.getDefaultInstance();

  GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(new ApacheHttpTransport(), factory)
      .setAudience(Collections.singletonList(HTTP_ENDPOINT))
      .build();

  String bearer = authorization.substring("Bearer ".length(), authorization.length());
  GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
  return idToken != null
    && verifier.verify(idToken)
    && idToken.getPayload().getEmailVerified()
    && idToken.getPayload().getEmail().equals(SERVICE_ACCOUNT_EMAIL);
}

Python

python/chat/secured-app/main.py

הצגת הקוד ב-GitHub

def verifyAddOnRequest() -> bool:
  """Determine whether a Google Workspace add-on request is legitimate.

  Args:
    request: Request sent from Google Workspace add-on

  Returns:
    Whether the request is legitimate
  """
  try:
    bearer = request.headers.get('Authorization')[len("Bearer "):]
    token = id_token.verify_oauth2_token(bearer, requests.Request(), HTTP_ENDPOINT)
    return token['email'] == SERVICE_ACCOUNT_EMAIL

  except:
    return False

Node.js

node/chat/secured-app/index.js

הצגת הקוד ב-GitHub

/**
 * Determine whether a Google Workspace add-on request is legitimate.
 * 
 * @param {Object} req Request sent from Google Workspace add-on
 * @return {boolean} Whether the request is legitimate
 */
async function verifyAddOnRequest(req) {
  try {
    const authorization = req.headers.authorization;
    const idToken = authorization.substring('Bearer '.length, authorization.length);
    const ticket = await new OAuth2Client().verifyIdToken({idToken, audience: HTTP_ENDPOINT});
    return ticket.getPayload().email_verified
        && ticket.getPayload().email === SERVICE_ACCOUNT_EMAIL;
  } catch (unused) {
    return false;
  }
}

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

אפליקציות ל-Chat שהן לא תוספים: אימות בקשות מ-Google Chat

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

באפליקציות ל-Chat שהן לא תוספים שהוגדרו עם כתובת URL של נקודת קצה HTTP בקטע הגדרות חיבור, הסוג של טוקן למוכ"ז והערך של השדה audience תלויים בסוג של קהל אימות שבחרתם כשהגדרתם את האפליקציה ל-Chat, והבקשות נחתמות על ידי חשבון השירות המשותף chat@system.gserviceaccount.com.

אימות בקשות באמצעות פונקציות Cloud Run (אפליקציות ל-Chat שלא מוגדרות כתוספים)

אם הלוגיקה של הפונקציה מיושמת באמצעות פונקציות Cloud Run, צריך לבחור באפשרות כתובת URL של נקודת קצה HTTP בשדה קהל היעד לאימות של הגדרת החיבור של אפליקציית Chat, ולוודא שכתובת ה-URL של נקודת הקצה HTTP בהגדרה תואמת לכתובת ה-URL של נקודת הקצה של פונקציית Cloud Run.

לאחר מכן, צריך לתת הרשאה לחשבון השירות של Google Chat‏ chat@system.gserviceaccount.com בתור מפעיל, באמצעות השלבים הבאים:

המסוף

אחרי שפורסים את הפונקציה או השירות ב-Google Cloud:

במסוף Google Cloud, עוברים לדף Cloud Run:

כניסה ל-Cloud Run
ברשימת שירותי Cloud Run, לוחצים על תיבת הסימון לצד הפונקציה המקבלת. (לא לוחצים על הפונקציה עצמה).
לוחצים על הרשאות בחלק העליון של המסך. נפתח החלונית הרשאות.
לוחצים על Add principal.
בשדה New principals, מזינים chat@system.gserviceaccount.com.
בתפריט Select a role (בחירת תפקיד), בוחרים בתפקיד Cloud Run.

‫Cloud Run Invoker.
לוחצים על שמירה.

gcloud

משתמשים בפקודה gcloud functions add-invoker-policy-binding:

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:chat@system.gserviceaccount.com'

מחליפים את RECEIVING_FUNCTION בשם הפונקציה של אפליקציית Chat.

אימות בקשות HTTP באמצעות טוקן של מזהה (אפליקציות ל-Chat שלא מוגדרות כתוספים)

אם השדה Authentication Audience של הגדרת החיבור של אפליקציית Chat שאינה תוסף מוגדר ל-HTTP endpoint URL, אסימון ההרשאה של bearer בבקשה הוא טוקן של מזהה של OpenID Connect ‏(OIDC) שנחתם על ידי Google. השדה email מוגדר ל-chat@system.gserviceaccount.com. השדה קהל לאימות מוגדר לכתובת ה-URL שהגדרתם ב-Google Chat לשליחת בקשות לאפליקציית Chat שהיא לא תוסף. לדוגמה, אם נקודת הקצה שהוגדרה לאפליקציית הצ'אט היא https://example.com/app/, אז השדה Authentication Audience בטוקן של מזהה הוא https://example.com/app/.

בדוגמאות הבאות מוצגות דרכים לאמת שאסימון ה-Bearer הונפק על ידי Google Chat ושהוא מיועד לאפליקציית Chat שלכם שאינה תוסף, באמצעות ספריית הלקוח של Google OAuth.

Java

java/basic-app/src/main/java/com/google/chat/app/basic/App.java

הצגת הקוד ב-GitHub

String CHAT_ISSUER = "chat@system.gserviceaccount.com";
JsonFactory factory = JacksonFactory.getDefaultInstance();

GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(new ApacheHttpTransport(), factory)
        .setAudience(Collections.singletonList(AUDIENCE))
        .build();

GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
return idToken != null
    && verifier.verify(idToken)
    && idToken.getPayload().getEmailVerified()
    && idToken.getPayload().getEmail().equals(CHAT_ISSUER);

Python

python/basic-app/main.py

הצגת הקוד ב-GitHub

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

try:
    # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
    request = requests.Request()
    token = id_token.verify_oauth2_token(bearer, request, AUDIENCE)
    return token['email'] == CHAT_ISSUER

except:
    return False

Node.js

node/basic-app/index.js

הצגת הקוד ב-GitHub

// Bearer Tokens received by apps will always specify this issuer.
const chatIssuer = 'chat@system.gserviceaccount.com';

// Verify valid token, signed by chatIssuer, intended for a third party.
try {
  const ticket = await client.verifyIdToken({
    idToken: bearer,
    audience: audience
  });
  return ticket.getPayload().email_verified
      && ticket.getPayload().email === chatIssuer;
} catch (unused) {
  return false;
}

אימות בקשות באמצעות JWT עם מספר פרויקט (אפליקציות ל-Chat שהן לא תוספים)

אם השדה Authentication Audience של הגדרת החיבור של אפליקציית Chat שלא מוגדרת כתוסף מוגדר ל-Project Number, אסימון ההרשאה מסוג bearer בבקשה הוא אסימון JWT‏ (JSON Web Token) בחתימה עצמית, שהונפק ונחתם על ידי chat@system.gserviceaccount.com. השדה audience מוגדר למספר הפרויקט ב-Google Cloud שבו השתמשתם כדי ליצור את אפליקציית Chat שאינה תוסף. לדוגמה, אם מספר פרויקט הענן של אפליקציית Chat הוא 1234567890, אז השדה audience ב-JWT הוא 1234567890.

בדוגמאות הבאות מוצגות דרכים לאמת שאסימון ה-Bearer הונפק על ידי Google Chat ושהוא מיועד לפרויקט שלכם באמצעות ספריית לקוח Google OAuth.

Java

java/basic-app/src/main/java/com/google/chat/app/basic/App.java

הצגת הקוד ב-GitHub

String CHAT_ISSUER = "chat@system.gserviceaccount.com";
JsonFactory factory = JacksonFactory.getDefaultInstance();

GooglePublicKeysManager keyManagerBuilder =
    new GooglePublicKeysManager.Builder(new ApacheHttpTransport(), factory)
        .setPublicCertsEncodedUrl(
            "https://www.googleapis.com/service_accounts/v1/metadata/x509/" + CHAT_ISSUER)
        .build();

GoogleIdTokenVerifier verifier =
    new GoogleIdTokenVerifier.Builder(keyManagerBuilder).setIssuer(CHAT_ISSUER).build();

GoogleIdToken idToken = GoogleIdToken.parse(factory, bearer);
return idToken != null
    && verifier.verify(idToken)
    && idToken.verifyAudience(Collections.singletonList(AUDIENCE))
    && idToken.verifyIssuer(CHAT_ISSUER);

Python

python/basic-app/main.py

הצגת הקוד ב-GitHub

# Bearer Tokens received by apps will always specify this issuer.
CHAT_ISSUER = 'chat@system.gserviceaccount.com'

try:
    # Verify valid token, signed by CHAT_ISSUER, intended for a third party.
    request = requests.Request()
    certs_url = 'https://www.googleapis.com/service_accounts/v1/metadata/x509/' + CHAT_ISSUER
    token = id_token.verify_token(bearer, request, AUDIENCE, certs_url)
    return token['iss'] == CHAT_ISSUER

except:
    return False

Node.js

node/basic-app/index.js

הצגת הקוד ב-GitHub

// Bearer Tokens received by apps will always specify this issuer.
const chatIssuer = 'chat@system.gserviceaccount.com';

// Verify valid token, signed by CHAT_ISSUER, intended for a third party.
try {
  const response = await fetch('https://www.googleapis.com/service_accounts/v1/metadata/x509/' + chatIssuer);
  const certs = await response.json();
  await client.verifySignedJwtWithCertsAsync(
    bearer, certs, audience, [chatIssuer]);
  return true;
} catch (unused) {
  return false;
}

אימות בקשות מ-Google Chat קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

אימות בקשות באמצעות פונקציות Cloud Run

המסוף

gcloud

אימות בקשות HTTP באמצעות טוקן של מזהה

Java

Python

Node.js

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

אפליקציות ל-Chat שהן לא תוספים: אימות בקשות מ-Google Chat

אימות בקשות באמצעות פונקציות Cloud Run (אפליקציות ל-Chat שלא מוגדרות כתוספים)

המסוף

gcloud

אימות בקשות HTTP באמצעות טוקן של מזהה (אפליקציות ל-Chat שלא מוגדרות כתוספים)

Java

Python

Node.js

אימות בקשות באמצעות JWT עם מספר פרויקט (אפליקציות ל-Chat שהן לא תוספים)

Java

Python

Node.js

אימות בקשות מ-Google Chat