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

שימוש ב- 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. כדי ליצור אישורי חשבון שירות או כדי להציג את האישורים הציבוריים שכבר יצרת, בצע את הפעולות הבאות:

  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 תשתמש בחשבון שירות כדי לגשת לממשק המשתמש של יומן Google. אישור חשבון שירות לגשת לנתונים בשם משתמשים בדומיין מכונה לעתים "האצלת סמכות חובקת תחום" לחשבון שירות.

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

לאחר מכן, מנהל על של תחום 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 מורשית

ג'אווה

לאחר שקיבלת את כתובת הדוא"ל הלקוח ואת המפתח הפרטי מן 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')

השתמש באובייקט האישורים כדי לקרוא לממשקי 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 באמצעות אלגוריתם hashing 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