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

מדריך להטמעת OAuth 2.1

במדריך הזה מוסבר איך לתת לפלטפורמת האפליקציות המקושרות הרשאה לגשת לשירותים שלכם בצורה מאובטחת. בשילובים של אפליקציות מקושרות עם MCP, מומלץ מאוד להשתמש ב-OAuth 2.1, התקן המקובל בתחום להרשאה מואצלת, עם Proof Key for Code Exchange ‏(PKCE) כדי להבטיח את רמת האבטחה הגבוהה ביותר לנתוני המשתמשים ואמינות בתהליכים של סוכני AI. פלטפורמת האפליקציות המקושרות תומכת בסוג grant של קוד ההרשאה עם פרמטרים של Proof Key for Code Exchange ‏(PKCE).

חובה להשתמש ב-PKCE בכל OAuth 2.1, ואפשר להשתמש בו ב-OAuth2.0.

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

איך Gemini MCP מאחזר את קובץ ה-JSON של ההגדרות האישיות

מסוף Gemini MCP מנסה לאחזר את קובץ ה-JSON של ההגדרות האישיות מכתובות ה-URL הבאות, לפי הסדר שמוצג בקטע הזה.

אם כתובת ה-URL של שרת ההרשאות נמצאת ברמה העליונה של הדומיין (לדוגמה, https://auth.example.com), Gemini מוסיף לדומיין ספריות סטנדרטיות מסוג well-known ומחפש את השרת בסדר הבא:

https://auth.example.com/.well-known/oauth-authorization-server
https://auth.example.com/.well-known/openid-configuration

אם כתובת ה-URL של שרת ההרשאות נמצאת בספריית משנה או בנתיב ספציפיים בדומיין, לדוגמה, https://auth.example.com/realms/master, ‏Gemini מוסיף את אותם נתיבים "מוכרים" ישירות לספריית המשנה הזו, בסדר הבא.

.../realms/master/.well-known/oauth-authorization-server
.../realms/master/.well-known/openid-configuration
‫.../realms/master/.well-known/openid-configuration (תמיכה בנתיבים בתצוגת עץ)

יכולות JSON נדרשות

תגובת המטא-נתונים חייבת לכלול את השדות הבאים. השילוב ייכשל אם חסרים שדות חובה או אם לא נמצאו סוגים חוקיים.

authorization_endpoint

הערך חייב להיות כתובת URL תקינה.

token_endpoint

הערך חייב להיות כתובת URL תקינה.

response_types_supported

חייב להכיל את המחרוזת code.

registration_endpoint

נכון לעכשיו, Play Console מסתמך על Dynamic Client.

(RFC 7591). צריך לספק נקודת קצה לרישום במטא-נתונים, או להזין את מזהה הלקוח או הסוד ישירות בממשק המשתמש של Play Console.

אם שרת ההרשאות שלכם לא תומך ב-Dynamic Client Registration‏ (DCR), אתם צריכים להטמיע באופן ידני את השדות מזהה לקוח וסוד לקוח ולאכלס אותם בממשק המשתמש של Play Console כדי להשלים את השילוב.

אם ההטמעה שלכם תומכת ב-Proof Key for Code Exchange‏ (PKCE) או בסשנים מתמשכים, אתם צריכים לכלול את שדות היכולות הרלוונטיים (כמו Challenge Methods ו-סוג grant) בקובץ ה-JSON של הגילוי. כך אפשר לוודא שהם תואמים לתקני האבטחה והקישוריות של Gemini. אם אתם תומכים בהיקף, אתם צריכים לכלול את השדה scopes_supported.

הגדרה לדוגמה

התגובה הבאה היא תגובת JSON תקינה שעומדת בדרישות של הלקוח שלנו.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

אם אתם כוללים PKCE, הקטע הבא מראה דוגמה למה שאפשר לכלול בבלוק ה-JSON.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

במקרים שבהם אתם כוללים את השדה scopes_supported, קטע הקוד הבא מראה דוגמה למה שאפשר לכלול בבלוק ה-JSON.

"scopes_supported": ["mcp", "cart.order"],

הרשאה באמצעות קוד (גרסה פשוטה)

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

בקשת הרשאה: הפלטפורמה של Google קובעת שהיא צריכה להפעיל את הפונקציה, אבל המשתמש עדיין לא קיבל הרשאה. הצ'אט בוט מתחיל את התהליך על ידי הפניית הדפדפן של המשתמש (או הצגת קישור) אל נקודת הקצה לאימות.

הבקשה הזו כוללת את מזהה הלקוח (או מזהה שנוצר באופן אוטומטי באמצעות DCR), את כתובת ה-URI להפניה אוטומטית של Gemini ואת הפרמטרים החשובים של PKCE (code_challenge ו-code_challenge_method).

מוסיפים את כתובות ה-URL הבאות לרשימת ההיתרים להגדרת OAuth:
- https://oauth-redirect.googleusercontent.com/r/*
- https://oauth-redirect-sandbox.googleusercontent.com/r/*
- https://oauth-redirect-test.googleusercontent.com/r/*
- https://oauth-redirect.googleusercontent.com/a/*
- https://oauth-redirect-sandbox.googleusercontent.com/a/*
- https://oauth-redirect-test.googleusercontent.com/a/*
הסכמת המשתמש: שרת ההרשאות מאמת את הבקשה, מאמת את המשתמש (התחברות) ומבקש מהמשתמש לתת לפלטפורמה של Google הרשאה לגשת לנתונים או לשירות שלו.
הענקת קוד: אחרי שהמשתמש נותן הסכמה מהמשתמש, השרת מפנה את הדפדפן של המשתמש בחזרה אל RedirectURI של Gemini, ומוסיף קוד הרשאה זמני לכתובת ה-URL.
החלפת טוקנים: הקצה העורפי של Gemini שולח בקשת POST לנקודת הקצה של הטוקן, ומחליף את קוד ההרשאה בטוקן גישה.

הערה: הבקשה הזו חייבת לכלול את הפרמטר PKCE‏ (code_verifier) כדי להוכיח שמדובר באותו לקוח שהתחיל את התהליך.
הגישה אושרה: נקודת הקצה של הטוקן מאמתת את הקוד ואת הפרמטרים של ה-PKCE, מנפיקה טוקן גישה (ואופציונלית גם טוקן רענון) ומחזירה אותם ל-Gemini.

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

הדרישות העיקריות של PKCE

‫PKCE מוסיף שכבת אבטחה כדי למנוע יירוט לא מורשה של קודי הרשאה.

‫code_verifier: מחרוזת אקראית קריפטוגרפית שנוצרת על ידי Gemini בתחילת התהליך. המידע הזה נשאר פרטי.
‫code_challenge: טרנספורמציה של code_verifier, בדרך כלל גיבוב SHA256. הוא נשלח באופן ציבורי, כמו שמתואר בשלב 1 של תהליך ההרשאה באמצעות קוד.
אימות: נקודת הקצה של האסימון (שמתוארת בשלב 4 של תהליך ההרשאה באמצעות קוד) צריכה לאמת שהערך של code_verifier שהתקבל תואם לערך המקורי של code_challenge אחרי שהוא עובר המרה.

ניפוי באגים

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

דרישות להגדרת קישור של חשבון Google

במדריך הבא ל-API מוסבר איך להגדיר קישור של חשבון Google.

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

שדה תצורה	תיאור	אחריות המפתחים
מזהה לקוח וסוד	פרטי הכניסה הייחודיים ששרת ההרשאות שלכם יוצר במיוחד בשביל פלטפורמת האפליקציות המקושרות. סוד הלקוח הוא פרטי הכניסה המאובטחים (הסיסמה) שמשויכים למזהה הלקוח. הערה: אם המפתח הנפיק את מזהה הלקוח, הוא צריך לספק אותו. אם Google הנפיקה את מזהה הלקוח, יכול להיות שהמפתח יצטרך לרשום סוד או לאמת אותו.	בכל בקשות ההרשאה, צריך להשתמש במזהה שסופק על ידי הפלטפורמה.
נקודת קצה להרשאה	כתובת ה-URL שאליה המשתמשים מופנים כדי לאמת את הזהות שלהם ולהביע הסכמה	מארחים את נקודת הקצה (endpoint) – לדוגמה, `https://yourdomain.com/oauth/authorize`
Token Endpoint	נקודת הקצה לקצה העורפי להחלפת קודי הרשאה באסימוני גישה או רענון, ולרענון אסימונים שפג תוקפם.	מארחים את נקודת הקצה הזו – לדוגמה, https://yourdomain.com/oauth/token
נקודת קצה לביטול אופציונלי	כתובת ה-URL שבה המערכת שלכם מקבלת הודעה על ביטול תוקף של אסימון כשמשתמש מתנתק. כשמשתמש מבטל את הקישור או מנתק את השילוב שלכם מתוך פלטפורמת האפליקציות המקושרות, אנחנו שולחים בקשת POST לנקודת הקצה ‎/revoke שמכילה את טוקן הגישה או טוקן הרענון. מידע נוסף זמין במאמר ביטול הקישור בין חשבונות.	מארחים את נקודת הקצה (endpoint) – לדוגמה, `https://yourdomain.com/oauth/revoke` השרת שלכם צריך לטפל בבקשה הזו על ידי ביטול תוקף האסימון שסופק באופן סופי. כך, כל ניסיון של פלטפורמת Connected apps להשתמש בטוקן הזה ייכשל, ושמירה על אבטחת המידע של המשתמש לאחר הניתוק.
‫URI של הפניה אוטומטית	כתובת ה-URL הספציפית של הקריאה החוזרת (callback) שסופקה על ידי הפלטפורמה, שאליה שרת ההרשאות שולח את הקוד בחזרה אחרי קבלת ההסכמה.	מגדירים את שרת ההרשאות כך שיקבל רק את כתובת ה-URI הרשמית והרשומה להפניה אוטומטית מהפלטפורמה.
רענון	`/token` עם `grant_type=refresh_token` מנגנון שמאפשר לפלטפורמת האפליקציות המקושרות לקבל טוקן גישה חדש כשהטוקן הנוכחי פג, כדי לשמור על החיבור של השילוב בלי שהמשתמש יצטרך להתחבר שוב ושוב. כשתוקף של טוקן גישה קיים יפוג, פלטפורמת האפליקציות המקושרות תשלח באופן אוטומטי בקשת `POST` לנקודת הקצה (endpoint) של `/token`. מטען הייעודי (payload) של הבקשה יכלול את `grant_type=refresh_token` יחד עם טוקן הרענון שהשרת שלכם הנפיק בעבר.	השרת שלכם צריך לאמת את טוקן הרענון שסופק ולהחזיר טוקן גישה חדש בתגובת ה-JSON. בנוסף, כדי להטמיע קישור מתמשך, צריך להימנע מרוטציה של טוקן הרענון במהלך ההחלפה הזו. במקום להנפיק טוקן חדש, צריך להחזיר את אותו טוקן רענון בדיוק בתגובת ה-JSON ולהאריך את תאריך התפוגה שלו בקצה העורפי.
סוג התגובה	כדי לתמוך בתהליך ההרשאה באמצעות קוד, צריך להגדיר את השדה הזה לערך CODE.
היקפים	קבוצה של הרשאות ורמות גישה ספציפיות שמגדירות מה האסימון מורשה לעשות. צריך להגדיר אותן מראש בהגדרות האישיות כדי ש-Google תוכל לבקש אותן במהלך לחיצת היד הראשונית של ההרשאה.	תצטרכו לספק רשימה של היקפי הרשאות שמוגדרים כברירת מחדל (לדוגמה, `openid, profile, email`) שפלטפורמת האפליקציות המקושרות צריכה לבקש כשהיא מתחילה את התהליך. היקפי ההרשאות המבוקשים צריכים להיות מצומצמים ככל האפשר (העיקרון של הרשאות מינימליות), אבל מספיקים לחלוטין לחוויות השימוש ההכרחיות (CUJ) שהשילוב של MCP תומך בהן.
נכסים של ממשק המשתמש: לוגו	לוגו המפתח שיוצג במסכי קישור החשבונות ומסך ההסכמה.	התמונה צריכה להיות תמונה וקטורית (SVG) ריבועית עם מראה מעוגל ובגודל של לפחות 500x500 פיקסלים. לדוגמה, אפשר לעיין ב-`https://[partner-domain]/assets/logo.svg` או בקובץ ה-SVG הגולמי.
קישור לאפליקציית נייטיב (App Flip)	כדי לתמוך בקישור חשבונות ישירות מהאפליקציות שלכם ל-Android או ל-iOS, מומלץ מאוד לא להסתמך על תצוגות אינטרנט רגילות. במקום זאת, מומלץ מאוד להטמיע את קישור אפליקציות כדי לספק חוויית שימוש חלקה. מידע נוסף זמין במאמר קישור של חשבון Google באמצעות קישור אפליקציות שמבוסס על OAuth.	כדי לוודא שהמעבר בין האפליקציות לצורך הרשאה מאובטח, צריך להשלים את האימות בחנות Play וב-App Store, ולהטמיע את כתובות ה-URI להפניה אוטומטית של Google ישירות באפליקציות הנייטיב.
משך החיים של הטוקן	(אופציונלי) משך הזמן שבו טוקן הגישה תקף לפני שצריך לרענן אותו. ההגדרה הזו שימושית להגדרת מדיניות של זמן קצוב לתפוגה ב-GAL.	זמני התפוגה הנפוצים נעים בין דקות, שעות וימים, בהתאם לצורכי האבטחה – לדוגמה, `30 days`)

שגיאות נפוצות בשילוב

ריכזנו כאן רשימה של שגיאות נפוצות ופתרונות אפשריים שרלוונטיים לתהליך השילוב.

חסרה הרשאת "קוד": המערכת האוטומטית של פלטפורמת Gemini בודקת באופן מפורש אם הערך "קוד" מופיע ב-response_types_supported.
חסרה נקודת קצה לרישום: גם אם השרת שלכם תומך במסמכי מטא-נתונים של מזהה לקוח, אפליקציית Gemini (שפועלת כלקוח OAuth שמתחבר לשרת שלכם) דורשת כרגע שיהיה registration_endpoint ייעודי ב-JSON של הגילוי.
שגיאה שאינה 200: אם מנגנון הגילוי האוטומטי של המטא-נתונים של Gemini מגיע לכתובת ה-URL מסוג well-known ומקבל את השגיאה 404 או 500, הוא לא ינסה לנחש כתובות URL אחרות. ודאו שכתובת ה-URL של הגילוי נגישה באופן ציבורי.