גוגל מחויבת לקידום הון גזעי לקהילות שחורות. תראה איך.

שימוש ב- OAuth 2.0 ליישומי שרת לשרת

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

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

מנהלי תחום של Google Workspace יכולים גם להעניק לחשבונות שירות סמכות רחבה בתחום לגשת לנתוני משתמשים בשם המשתמשים בתחום.

מסמך זה מתאר כיצד יישום יכול להשלים את זרימת OAuth 2.0 בין שרת לשרת באמצעות ספריית לקוח API של Google (מומלץ) או HTTP.

סקירה כללית

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

לאחר מכן, היישום שלך מתכונן לבצע שיחות API מורשות באמצעות אישורי חשבון השירות כדי לבקש אסימון גישה משרת האימות OAuth 2.0.

לבסוף, היישום שלך יכול להשתמש באסימון הגישה כדי להתקשר לממשקי API של Google.

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

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

אם היישום שלך פועל ב- Google App Engine, חשבון שירות מוגדר אוטומטית בעת יצירת הפרויקט שלך.

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

אם היישום שלך לא פועל ב- Google App Engine או ב- Google Compute Engine, עליך לקבל את האישורים האלה ב- Google API Console. כדי ליצור אישורי חשבון שירות, או כדי להציג את האישורים הציבוריים שכבר יצרת, בצע את הפעולות הבאות:

  1. פתח את Service accounts page .
  2. If prompted, select a project, or create a new one.
  3. לחץ על צור חשבון שירות .
  4. תחת פרטי חשבון השירות , הקלד שם, מזהה ותיאור עבור חשבון השירות ולחץ על צור .
  5. אופציונלי: תחת הרשאות חשבון שירות , בחר בתפקידי IAM להעניק לחשבון השירות ולחץ על המשך .
  6. אופציונלי: תחת הענק למשתמשים גישה לחשבון שירות זה , הוסף את המשתמשים או הקבוצות שמורשים להשתמש ולנהל את חשבון השירות.
  7. לחץ על מקש Create ולאחר מכן לחץ על צור .

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

אם אתה צריך להעניק סמכות לרוחב התחום של G Suite לחשבון השירות, לחץ על כתובת הדוא"ל של חשבון השירות שיצרת והעתק את הערך מתיבת הזיהוי הייחודי .

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

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

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

האצלת סמכות רחבת תחום לחשבון השירות

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

כדי להאציל סמכות לכל הדומיינים לחשבון שירות, ראשית הפעל האצלה לכלל תחום עבור חשבון שירות קיים ב- Service accounts page או צור חשבון שירות חדש עם הפעלת האצלה בכל תחום.

לאחר מכן, מנהל על של תחום Google Workspace חייב לבצע את השלבים הבאים:

  1. מ של תחום העבודה של Google שלך במסוף הניהול , עבור אל תפריט ראשי > אבטחה> בקרת API.
  2. בחלונית האצלה של תחום רחב , בחר נהל משלחת רחבה של תחומים .
  3. לחץ על הוסף חדש .
  4. בשדה זיהוי לקוח , הזן את מזהה הלקוח של חשבון השירות. אתה יכול למצוא את מספר הלקוח של חשבון השירות שלך בטלפון Service accounts page.
  5. בשדה טווחי OAuth (מופרדים בפסיקים) , הזן את רשימת היקפים שאליהם יש להעניק גישה ליישום שלך. לדוגמה, אם היישום שלך זקוק לגישה מלאה של תחום ל- API של כונן Google ול- API של יומן Google, הזן: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth / לוח שנה .
  6. לחץ על אשר.

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

מתכונן לביצוע שיחת API מורשית

ג'אווה

לאחר שתקבל את כתובת הדוא"ל של הלקוח ואת המפתח הפרטי מ- API Console, השתמש בספריית הלקוחות של Google APIs עבור Java כדי ליצור אובייקט GoogleCredential חשבון השירות GoogleCredential היישום שלך זקוקים לגישה אליו. לדוגמה:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

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

האציל סמכות רחבה בתחום

אם הקצאת גישה לכל תחום לחשבון השירות ואתה רוצה להתחזות לחשבון משתמש, ציין את כתובת הדוא"ל של חשבון המשתמש בשיטה createDelegated של האובייקט GoogleCredential . לדוגמה:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("user@example.com");

השתמש באובייקט GoogleCredential כדי להתקשר לממשקי API של Google ביישום שלך.

פִּיתוֹן

לאחר שתקבל את כתובת הדוא"ל של הלקוח והמפתח הפרטי מה- API Console, השתמש בספריית הלקוחות של Google APIs עבור Python כדי להשלים את השלבים הבאים:

  1. צור אובייקט Credentials חשבון השירות ומהיקפי היישום שלך זקוקים לגישה. לדוגמא:
    from google.oauth2 import service_account
    
    SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
    SERVICE_ACCOUNT_FILE = '/path/to/service.json'
    
    credentials = service_account.Credentials.from_service_account_file(
            SERVICE_ACCOUNT_FILE, scopes=SCOPES)

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

  2. האציל סמכות רחבה בתחום

    אם with_subject גישה לכל תחום לחשבון השירות ואתה רוצה להתחזות לחשבון משתמש, השתמש בשיטת with_subject של אובייקט ServiceAccountCredentials קיים. לדוגמה:

    delegated_credentials = credentials.with_subject('user@example.org')

השתמש באובייקט האישורים כדי להתקשר לממשקי API של Google ביישום שלך.

HTTP / REST

לאחר שתקבל את מזהה הלקוח והמפתח הפרטי מה- API Console, היישום שלך צריך לבצע את השלבים הבאים:

  1. צור אסימון אינטרנט של JSON (JWT, מבוטא, "jot") הכולל כותרת, ערכת תביעה וחתימה.
  2. בקש אסימון גישה משרת OAuth 2.0 של Google.
  3. טפל בתגובת JSON שהשרת Authorization מחזיר.

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

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

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

יישום השרת שלך משתמש ב- JWT כדי לבקש אסימון משרת הרשאות Google, ואז משתמש באסימון כדי להתקשר לנקודת קצה של Google API. אין משתמש קצה מעורב.

שאר חלק זה מתאר את הפרטים של יצירת JWT, חתימה על JWT, יצירת בקשת אסימון הגישה וטיפול בתגובה.

יצירת JWT

JWT מורכב משלושה חלקים: כותרת, ערכת תביעה וחתימה. הכותרת ומערכת התביעות הם אובייקטים של JSON. אובייקטים JSON אלה מסודרים לסדרת UTF-8 בתים, ואז מקודדים באמצעות קידוד Base64url. קידוד זה מספק חוסן נגד שינויי קידוד עקב פעולות קידוד חוזרות. הכותרת, קבוצת התביעות והחתימה משורשרות יחד עם תו נקודה ( . ).

JWT מורכב כדלקמן:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

מחרוזת הבסיס לחתימה היא כדלקמן:

{Base64url encoded header}.{Base64url encoded claim set}
יצירת כותרת JWT

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

חשבונות שירות מסתמכים על האלגוריתם RSA SHA-256 ועל פורמט האסימונים JWT. כתוצאה מכך, ייצוג הכותרת של JSON הוא כדלקמן:

{"alg":"RS256","typ":"JWT"}

ייצוג Base64url זה הוא כדלקמן:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
גיבוש מערך התביעות של JWT

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

תביעות נדרשות

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

שֵׁם תיאור
iss כתובת הדוא"ל של חשבון השירות.
scope רשימה המופרדת מהחלל של ההרשאות שהבקשה מבקשת.
aud מתאר מטרת הקביעה המיועדת. בעת ביצוע בקשת אסימון גישה ערך זה הוא תמיד https://oauth2.googleapis.com/token .
exp זמן התפוגה של הקביעה, שצוין כשניות מאז 00:00:00 UTC, 1 בינואר 1970. לערך זה יש לכל היותר שעה לאחר השעה שהונפקה.
iat מועד הוצאת הקביעה, שצוין כשניות מאז 00:00:00 UTC, 1 בינואר 1970.

ייצוג JSON של השדות הנדרשים בערכת תביעה של JWT מוצג להלן:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
תביעות נוספות

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

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

שֵׁם תיאור
sub כתובת הדוא"ל של המשתמש שעבורו האפליקציה מבקשת גישה מאושרת.

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

דוגמה למערכת תביעה של JWT הכוללת את שדה sub מוצגת להלן:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
קידוד מערך התביעות של JWT

כמו כותרת JWT, יש לסדר את ערכת התביעות של JWT לסידור UTF-8 ולקידוד Safe64url. להלן דוגמה לייצוג JSON של קבוצת תביעה של JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
מחשוב החתימה

JSON Web Signature (JWS) הוא המפרט שמנחה את מכניקת יצירת החתימה עבור ה- JWT. הקלט לחתימה הוא מערך הבתים של התוכן הבא:

{Base64url encoded header}.{Base64url encoded claim set}

יש להשתמש באלגוריתם החתימה בכותרת JWT בעת חישוב החתימה. אלגוריתם החתימה היחיד הנתמך על ידי שרת ההרשאה של Google OAuth 2.0 הוא RSA המשתמש באלגוריתם הגיבוב של SHA-256. זה מבוטא RS256 של alg השדות בכותרת JWT.

חתום על ייצוג ה- UTF-8 של הקלט באמצעות SHA256withRSA (המכונה גם RSASSA-PKCS1-V1_5-SIGN עם פונקציית ה- Hash של SHA-256) באמצעות המפתח הפרטי המתקבל מה- Google API Console. הפלט יהיה מערך בתים.

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

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

להלן דוגמה ל- JWT לפני קידוד Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

להלן דוגמה ל- JWT שנחתם ומוכן להעברה:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

ביצוע בקשת אסימון הגישה

לאחר יצירת ה- JWT החתום, יישום יכול להשתמש בו לבקשת אסימון גישה. בקשת אסימון גישה זו היא בקשת HTTPS POST , והגוף מקודד לכתובת URL. כתובת האתר מוצגת למטה:

https://oauth2.googleapis.com/token

הפרמטרים הבאים נדרשים בבקשת HTTPS POST :

שֵׁם תיאור
grant_type השתמש במחרוזת הבאה, המקודדת לכתובת URL לפי הצורך: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion ה- JWT, כולל חתימה.

להלן מזבלה גולמית של בקשת HTTPS POST המשמשת בבקשת אסימון גישה:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

להלן אותה בקשה, תוך שימוש curl :

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

טיפול בתגובה

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

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

ניתן לעשות שימוש חוזר באסימוני גישה במהלך חלון משך הזמן שצוין על ידי הערך expires_in .

מתקשר לממשקי API של גוגל

ג'אווה

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

  1. צור אובייקט שירות עבור ה- API שאליו ברצונך להתקשר באמצעות האובייקט GoogleCredential . לדוגמא:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. הגיש בקשות לשירות ה- API באמצעות הממשק שמספק אובייקט השירות . לדוגמא, כדי לרשום את המופעים של מסדי נתונים של Cloud SQL בפרויקט מרגש לדוגמא 123:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

פִּיתוֹן

השתמש מורשי Credentials מתנגדים להתקשר Google APIs ידי השלמת השלבים הבאים:

  1. בנה אובייקט שירות עבור ה- API שאליו ברצונך להתקשר. אתה בונה אובייקט שירות על ידי קריאה לפונקציית build עם השם והגרסה של ה- API ואובייקט Credentials המורשים. לדוגמה, להתקשר לגרסה 1 בטא 3 של ממשק ה- API של ניהול SQL Cloud:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. הגיש בקשות לשירות ה- API באמצעות הממשק שמספק אובייקט השירות . לדוגמה, כדי לרשום את המופעים של מסדי נתונים של Cloud SQL בפרויקט מרגש לדוגמא 123:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP / REST

לאחר שהיישום שלך משיג אסימון גישה, באפשרותך להשתמש באסימון לביצוע שיחות ל- API של גוגל מטעם חשבון שירות או חשבון משתמש נתון אם הוענקו היקף הגישה הנדרש על ידי ה- API. לשם כך, access_token את אסימון הגישה בבקשה לממשק ה- API על ידי הכללת פרמטר שאילתת access_token או ערך Bearer כותרת HTTP של Authorization . במידת האפשר עדיף כותרת HTTP מכיוון שמחרוזות שאילתה נוטות להיות גלויות ביומני השרת. ברוב המקרים אתה יכול להשתמש בספריית לקוחות כדי להגדיר את השיחות שלך לממשקי API של Google (למשל, בעת קריאה ל- Drive Files API ).

אתה יכול לנסות את כל ממשקי ה- API של Google ולהציג את היקפיהם בגן המשחקים OAuth 2.0 .

דוגמאות ל- HTTP GET

שיחה drive.files הקצה של drive.files (ה- API של קבצי Drive) באמצעות כותרת ה- Authorization: Bearer HTTP עשויה להיראות כמו הבאה. שים לב שעליך לציין את אסימון הגישה שלך:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

הנה קריאה לאותו API עבור המשתמש המאומת באמצעות פרמטר מחרוזת השאילתה access_token :

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

דוגמאות curl

באפשרותך לבדוק פקודות אלה באמצעות יישום שורת הפקודה curl . הנה דוגמה המשתמשת באפשרות כותרת HTTP (מועדפת):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

לחלופין, אפשרות פרמטר מחרוזת השאילתה:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

כאשר תוקף אסימוני הגישה פג

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

קודי שגיאה של JWT

שדה error שדה error_description מַשְׁמָעוּת כיצד לפתור
unauthorized_client Unauthorized client or scope in request. אם אתה מנסה להשתמש בהאצלה הכוללת תחום, חשבון השירות אינו מורשה במסוף הניהול של הדומיין של המשתמש.

ודא שחשבון השירות מורשה בדף ההאצלה הרחב של תחום הניהול עבור המשתמש בתביעת sub (שדה).

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

unauthorized_client Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. חשבון שירות אושר באמצעות כתובת הדוא"ל של הלקוח במקום מזהה הלקוח (המספרי) במסוף הניהול. בדף המשלחת הרחב של תחום במסוף הניהול, הסר את הלקוח והוסף אותו מחדש עם המזהה המספרי.
access_denied (כל ערך) אם אתה משתמש במשלחת הכוללת תחום, היקף מבוקש אחד או יותר אינם מורשים במסוף הניהול.

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

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

invalid_grant Not a valid email. המשתמש לא קיים. בדוק שכתובת הדוא"ל בתביעת sub (שדה) נכונה.
invalid_grant

Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.

בדרך כלל, המשמעות היא שזמן המערכת המקומי אינו נכון. זה יכול לקרות גם אם ערך ה- exp יהיה בעתיד יותר מ- 65 דקות מערך ה- iat , או שערך ה- exp יהיה נמוך מערך ה- iat .

וודא שהשעון במערכת בו נוצר ה- JWT תקין. במידת הצורך, סנכרן את הזמן שלך עם Google NTP .

invalid_grant Invalid JWT Signature.

קביעת JWT נחתמת באמצעות מפתח פרטי שאינו משויך לחשבון השירות שזוהה על ידי דוא"ל הלקוח.

לחלופין, קביעת JWT עשויה להיות מקודדת באופן שגוי - עליה להיות מקודדת ב- Base64, ללא קווים חדשים או ריפוד שווה.

פענח את מערך התביעות של JWT וודא שהמפתח שחתם על הקביעה משויך לחשבון השירות.

נסה להשתמש בספריית OAuth שמספקת Google כדי לוודא שה- JWT נוצר כהלכה.

invalid_scope Invalid OAuth scope or ID token audience provided. לא התבקש היקף (רשימת טווחים ריקה), או שאחד מההיקפים המבוקשים אינו קיים (כלומר אינו חוקי).

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

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

disabled_client The OAuth client was disabled. המפתח המשמש לחתימה על קביעת JWT מושבת.

עבור אל Google API Console, ותחת IAM & Admin> חשבונות שירות , הפעל את חשבון השירות המכיל את "מזהה המפתח" המשמש לחתימת הטענה.

תוספת: הרשאת חשבון שירות ללא OAuth

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

אם ל- API שאליו אתה רוצה להתקשר יש הגדרת שירות המתפרסמת במאגר GitHub של ממשקי ה- API של Google , תוכל לבצע שיחות API מורשות באמצעות JWT במקום אסימון גישה. לשם כך:

  1. צור חשבון שירות כמתואר לעיל. הקפד לשמור על קובץ JSON שתקבל בעת יצירת החשבון.
  2. באמצעות כל ספריית JWT סטנדרטית, כמו זו שנמצאת ב- jwt.io , צור JWT עם כותרת ועומס מטען כמו הדוגמה הבאה:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • עבור שדה kid בכותרת, ציין את מזהה המפתח הפרטי של חשבון השירות שלך. אתה יכול למצוא ערך זה בשדה private_key_id של קובץ JSON של חשבון השירות שלך.
    • עבור iss ו sub תחומים, ציין את כתובת הדוא"ל של חשבון השירות שלך. אתה יכול למצוא ערך זה בשדה client_email של קובץ JSON של חשבון השירות שלך.
    • עבור שדה aud , ציין את נקודת הקצה של ה- API. לדוגמא: https:// SERVICE .googleapis.com/ .
    • עבור שדה iat , ציין את זמן יוניקס הנוכחי, ובשביל שדה exp , ציין את השעה בדיוק 3600 שניות לאחר מכן, כאשר ה- JWT יפוג.

חתום על ה- JWT באמצעות RSA-256 באמצעות המפתח הפרטי שנמצא בקובץ JSON של חשבון השירות שלך.

לדוגמה:

ג'אווה

שימוש ב- google-api-java-client ו- java-jwt :

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

פִּיתוֹן

שימוש ב- PyJWT :

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')
  1. התקשר ל- API, תוך שימוש ב- JWT החתום כאסימון הנושא:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com