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

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

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

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

מסמך זה מתאר כיצד יישום יכול להשלים את זרימת השרת לשרת OAuth 2.0 באמצעות ספריית לקוח של Google APIs (מומלץ) או 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. כדי ליצור אישורים של חשבון שירות, או כדי להציג את האישורים הציבוריים שכבר יצרת, בצע את הפעולות הבאות:

First, create a service account:

  1. Open the Service accounts page.
  2. If prompted, select a project, or create a new one.
  3. Click  Create service account.
  4. Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
  5. Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
  6. Click Continue.
  7. Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
  8. Click Done.
  9. Click  Create key, then click Create.

Next, create a service account key:

  1. Click the email address for the service account you created.
  2. Click the Keys tab.
  3. In the Add key drop-down list, select Create new key.
  4. Click Create.

Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.

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

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

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

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

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

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

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

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

Java

לאחר שקיבלת את כתובת הדוא"ל הלקוח ואת המפתח הפרטי מן API Console, להשתמש בספריית לקוח Google APIs עבור Java ליצור 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 האובייקט להתקשר Google APIs ביישום שלך.

פִּיתוֹן

לאחר שקיבלת את כתובת הדוא"ל הלקוח ואת המפתח הפרטי מן 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 השיטה קיים ServiceAccountCredentials אובייקט. לדוגמה:

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

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

HTTP/REST

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

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

הסעיפים הבאים מתארים כיצד להשלים שלבים אלה.

אם התגובה כוללת אסימון גישה, אתה יכול להשתמש בגישת אסימון כדי להתקשר API Google . (אם התשובה אינה כוללת אסימון גישה, ייתכן שבקשת ה- 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 ולקידוד בטוח ל- Base64url. להלן דוגמה לייצוג 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 (JWS) היא מפרט כי המדריכים את המכניקה של יצירת החתימה עבור JWT. הקלט עבור החתימה הוא מערך הבתים של התוכן הבא:

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

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

הרשמה ייצוג UTF-8 של קלט באמצעות SHA256withRSA (הידוע גם בשם-SIGN RSASSA-PKCS1-V1_5 עם פונקציית 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 בקשה, והגוף הוא כתובת האתר מקודד. כתובת האתר מוצגת למטה:

https://oauth2.googleapis.com/token

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

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

להלן dump גלם של 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 של Google

ג'אווה

השתמש GoogleCredential האובייקט להתקשר Google APIs ידי השלמת השלבים הבאים:

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

פִּיתוֹן

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

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

HTTP/REST

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

אתה יכול לנסות את כל Google APIs ולהציג ההיקפים שלהם בבית OAuth 2.0 מגרש .

HTTP GET דוגמאות

קריאת drive.files נקודה הקצה (ה- API קבצי כונן) באמצעות 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

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

גישה אסימוני שהוציאה שרת Authorization 2.0 Google OAuth לפוג לאחר תקופת שמספקת 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 מאוכלס, ולהשוות את ההיקפים שהוא מכיל עם ההיקפים תיעד עבור APIs אתה רוצה להשתמש, כדי לוודא שאין טעויות או שגיאות הקלדה.

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

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

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

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

עם כמה ממשקי API של Google, תוכל לבצע שיחות API מורשות באמצעות JWT חתום ישירות כאסימון נושאים, במקום אסימון גישה OAuth 2.0. כאשר הדבר אפשרי, תוכל להימנע מהצורך לבצע בקשת רשת לשרת ההרשאות של Google לפני ביצוע קריאת 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-לקוח ו 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