בדף הזה מתואר היישום של Google כספק OpenID Connect, ומופיע בו מידע טכני על נקודות הקצה של OIDC ב-Google. במפרט OpenID Connect (OIDC) Core 1.0 מוגדר הפרוטוקול לאימות משתמשים ולאחזור פרטי זהות.
המסמך הזה לא נועד לספק הוראות מפורטות להטמעה של OIDC. פרטים על ההטמעה מופיעים במדריך OpenID Connect.
מסמך Discovery
מסמך ה-Discovery מכיל מטא-נתונים על ההגדרה של OpenID Connect ב-Google, כפי שמוגדר במפרט OpenID Connect Discovery 1.0.
כתובת ה-URL: https://accounts.google.com/.well-known/openid-configuration
שיטת בקשה נתמכת: GET
גוף התשובה
שדות התגובה מוחזרים באובייקט JSON בגוף של תגובת ה-HTTP לבקשת GET של השולח אל https://accounts.google.com/.well-known/openid-configuration.
| שדה | סוג | תיאור |
|---|---|---|
issuer |
string |
מזהה המוסד המנפיק. כתובת URL תלוית-אותיות רישיות באמצעות הסכימה https. הערך המודרני הוא https://accounts.google.com, אבל גם הערך accounts.google.com מוחזר בהטמעות מדור קודם. |
authorization_endpoint |
string |
כתובת ה-URL של נקודת הקצה להרשאה. |
device_authorization_endpoint |
string |
כתובת ה-URL של נקודת הקצה להרשאת המכשיר. |
token_endpoint |
string |
כתובת ה-URL של נקודת הקצה של הטוקן. |
userinfo_endpoint |
string |
כתובת ה-URL של נקודת הקצה של פרטי המשתמש. |
revocation_endpoint |
string |
כתובת ה-URL של נקודת הקצה לביטול. |
jwks_uri |
string |
כתובת ה-URL של מסמך JSON Web Key Set (JWKS). |
response_types_supported |
array |
רשימה של ערכים נתמכים של response_type. |
response_modes_supported |
array |
רשימה של ערכים נתמכים של response_mode. |
authorization_response_iss_parameter_supported |
boolean |
ערך בוליאני שמציין תמיכה ב-RFC 9207. |
subject_types_supported |
array |
רשימה של סוגי מזהי נושאים נתמכים. |
id_token_signing_alg_values_supported |
array |
רשימה של אלגוריתמים נתמכים לחתימה על טוקן ה-ID. |
scopes_supported |
array |
רשימה של ערכי היקף נתמכים. |
claims_supported |
array |
רשימה של תלונות נתמכות על הפרת זכויות יוצרים. |
token_endpoint_auth_methods_supported |
array |
רשימה של שיטות אימות נתמכות לנקודת הקצה של הטוקן. |
code_challenge_methods_supported |
array |
רשימה של שיטות אתגר קוד נתמכות ל-PKCE. |
grant_types_supported |
array |
רשימה של סוגי הרשאות נתמכים של OAuth 2.0. |
אסימון מזהה (טענות)
הערך id_token שמוחזר בתשובות הוא טוקן אינטרנט בפורמט JSON (JWT) חתום, שצריך לאמת באמצעות חומר המפתח שהתקבל מהערך jwks_uri שנמצא במסמך הגילוי. בטבלה הבאה מתואר התוכן של מטען הייעודי (payload) של אסימון המזהה שפוענח.
| מימוש | סוג | תיאור |
|---|---|---|
iss |
string |
חובה. מזהה המוסד המנפיק של התשובה. בדרך כלל https://accounts.google.com, אבל גם accounts.google.com מוחזר להטמעות מדור קודם. |
sub |
string |
חובה. מזהה של המשתמש, ייחודי בין כל חשבונות Google ואי אפשר לעשות בו שימוש חוזר. לחשבון Google יכולות להיות כמה כתובות אימייל בנקודות זמן שונות, אבל הערך sub אף פעם לא משתנה. משתמשים ב-sub באפליקציה כמפתח של המזהה הייחודי של המשתמש. אורך מקסימלי של 255 תווים ב-ASCII, תלוי אותיות רישיות. |
azp |
string |
מזהה הלקוח של המציג המורשה, שמתקבל ממסוף Google Cloud. הטענה הזו נדרשת רק אם הצד שמבקש את טוקן ה-ID הוא לא אותו צד שמוגדר כקהל של טוקן ה-ID. |
aud |
string |
חובה. הקהל שאליו מיועד אסימון המזהה. זהו מזהה הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
iat |
integer |
חובה. השעה שבה הונפק אסימון הזהות. הערך מוצג כזמן ראשית זמן יוניקס (Unix epoch) (מספר שלם של שניות). |
exp |
integer |
חובה. שעת התפוגה שעד אליה או אחריה אסור לקבל את טוקן המזהה. הערך מוצג כזמן ראשית זמן יוניקס (Unix epoch) (מספר שלם של שניות). |
nonce |
string |
הערך של nonce שסופק על ידי האפליקציה בבקשת האימות. כדי להגן מפני התקפות שליחה מחדש, צריך להציג את הערך הזה רק פעם אחת. |
auth_time |
integer |
הזמן שבו התבצע אימות המשתמש, מספר JSON שמייצג את מספר השניות שחלפו מאז ראשית זמן יוניקס (1 בינואר 1970, 00:00:00 UTC). הערך הזה מסופק כשהתביעה auth_time נכללת בפרמטר claims של בקשת האימות. |
at_hash |
string |
גיבוב (hash) של טוקן הגישה. מספק אימות לכך שאסימון הגישה קשור לאסימון הזהות. אם אסימון המזהה מונפק עם ערך access_token בתהליך בצד השרת, ההצהרה הזו תמיד נכללת. |
email |
string |
כתובת האימייל של המשתמש. המידע הזה מסופק רק אם כללתם את היקף ההרשאות email בבקשה. הערך של הטענה הזו לא בהכרח ייחודי לחשבון הזה, והוא עשוי להשתנות עם הזמן. לכן, לא מומלץ להשתמש בערך הזה כמזהה הראשי לקישור לרשומת המשתמש. בנוסף, אי אפשר להסתמך על הדומיין של טענת email כדי לזהות משתמשים בארגונים של Google Workspace או Cloud. במקום זאת, צריך להשתמש בטענת hd. אזהרה: אל תשתמשו בכתובת אימייל כמזהה, כי לחשבון Google יכולות להיות כמה כתובות אימייל בנקודות זמן שונות. תמיד משתמשים בשדה sub כמזהה של המשתמש. |
email_verified |
boolean |
הערך יהיה True אם כתובת האימייל של המשתמש אומתה, אחרת הערך יהיה False. |
name |
string |
השם המלא של המשתמש, בפורמט שניתן להצגה. יכול להיות שהאסימון יסופק אם היקף הבקשה כולל את המחרוזת profile או אם אסימון המזהה מוחזר מרענון אסימון. |
picture |
string |
כתובת ה-URL של תמונת הפרופיל של המשתמש. יכול להיות שהפרמטר הזה יסופק אם היקף הבקשה כולל את המחרוזת profile או אם אסימון המזהה מוחזר מרענון אסימון. |
given_name |
string |
השם הפרטי של המשתמש. אפשר לציין זאת כשיש תביעה בנושא name. |
family_name |
string |
שם המשפחה של המשתמש. אפשר לציין זאת כשיש תביעה בנושא name. |
hd |
string |
הדומיין שמשויך לארגון Google Workspace או Cloud של המשתמש. הערך הזה מסופק רק אם המשתמש שייך לארגון ב-Google Cloud. צריך לסמן את הטענה הזו כשמגבילים את הגישה למשאב רק לחברים בדומיינים מסוימים. אם התביעה הזו לא מופיעה, סימן שהחשבון לא שייך לדומיין שמארח את Google. |
Authorization Endpoint
נקודת הקצה להרשאה משמשת לאימות המשתמש ולקבלת קוד הרשאה או טוקנים.
כתובת ה-URL: https://accounts.google.com/o/oauth2/v2/auth
שיטות בקשה נתמכות: GET, POST
פרמטרים של בקשה
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
client_id |
string |
חובה | מחרוזת מזהה הלקוח שמתקבלת ממסוף Google Cloud. |
nonce |
string |
אופציונלי | ערך אקראי שנוצר על ידי האפליקציה ומאפשר הגנה מפני שידור חוזר. נדרש רק אם מבקשים טוקן מזהה (כאשר response_type כולל id_token). |
response_type |
string |
חובה | הגדרה שקובעת באיזה תהליך להשתמש. אם הערך הוא code, מתחיל תהליך הרשאה באמצעות קוד, שדורש POST לנקודת הקצה של האסימון כדי לקבל את האסימונים. אם הערך הוא token, id_token, token id_token או id_token token, מתבצעת הפעלה של זרם הענקת גישה משתמע, שדורשת שימוש ב-JavaScript ב-URI של ההפניה לכתובת אחרת כדי לאחזר טוקנים מקטע ה-URI. מומלץ מאוד לא להשתמש ב-token בשום צורה, כי הוא חושף את טוקני הגישה בכתובת ה-URL. הערך הזה אסור ב-OAuth 2.1. |
response_mode |
string |
אופציונלי | המדיניות מציינת איך מועברת תגובת ההרשאה. אם הערך של response_type הוא code, ברירת המחדל היא query. לסוגי תשובות אחרים, ברירת המחדל היא fragment. ערכים נתמכים: query, fragment, form_post. |
redirect_uri |
string |
חובה | קובע לאן התשובה תישלח. הערך של הפרמטר הזה צריך להיות זהה לאחד מערכי ההפניה האוטומטית המורשים שהגדרתם במסוף Google Cloud (כולל סכימת ה-HTTP או ה-HTTPS, האותיות הרישיות והסלאש בסוף, אם יש). כתובות ה-URI להפניה אוטומטית ומקורות ה-JavaScript המורשים צריכים לעמוד בכללי האימות שמפורטים במסמכי התיעוד בנושא אימות כתובות URI ב-OAuth 2.0. |
scope |
string |
חובה | רשימה לא מסודרת של היקפי הרשאות, שמופרדת ברווחים. הרשימה חייבת לכלול את הערך openid ואז את הערך profile, את הערך email או את שניהם. אפשר גם לכלול היקפי הרשאות שאינם OIDC. אם הערך של היקף ההרשאות profile קיים, יכול להיות שטוקן ה-ID יכלול את טענות ברירת המחדל של profile המשתמש (אבל אין בכך ערובה). אם קיים ערך ההיקף email, טוקן ה-ID כולל את הטענות email ו-email_verified. מידע נוסף זמין במאמר בנושא היקפי הרשאות של OAuth 2.0. |
state |
string |
מומלץ | מחרוזת אטומה שמועברת הלוך ושוב בפרוטוקול. כלומר, היא מוחזרת כפרמטר URI בתהליך של הרשאה באמצעות קוד, ובמקטע ה-URI בזרם הענקת גישה משתמע. ה-state יכול להיות שימושי כדי ליצור קורלציה בין בקשות ותגובות. מכיוון שאפשר לנחש את הערך של redirect_uri, שימוש בערך state יכול להגביר את הביטחון שחיבור נכנס הוא תוצאה של בקשת אימות שהופעלה על ידי האפליקציה שלכם. כך אפשר להגן על האפליקציה מפני מתקפות כמו זיוף בקשה בין אתרים. |
access_type |
string |
אופציונלי | הערכים המותרים הם offline ו-online. אם האפליקציה צריכה לרענן את אסימוני הגישה כשהמשתמש לא נמצא בדפדפן, צריך להשתמש ב-offline. הערך הזה נדרש כדי לקבל אסימון רענון. |
hd |
string |
אופציונלי | לייעל את תהליך הכניסה לחשבונות שנמצאים בבעלות של ארגון ב-Google Cloud. אם כוללים את הדומיין של הארגון ב-Google Cloud (לדוגמה, mycollege.edu), אפשר לציין שממשק המשתמש לבחירת חשבון צריך להיות מותאם לחשבונות בדומיין הזה. כדי לבצע אופטימיזציה לחשבונות ארגוניים ב-Google Cloud באופן כללי, ולא רק לדומיין ארגוני אחד ב-Google Cloud, צריך להגדיר ערך של כוכבית (*): hd=*. |
login_hint |
string |
אופציונלי | כשהאפליקציה יודעת איזה משתמש מנסה לבצע אימות, היא יכולה לספק את הפרמטר הזה כרמז לשרת האימות. העברת הרמז הזה משביתה את הכלי לבחירת חשבון וממלאת מראש את תיבת האימייל בטופס הכניסה או בוחרת את הסשן המתאים. כך אפשר להימנע מבעיות שמתרחשות אם האפליקציה מתחברת לחשבון משתמש שגוי. הערך יכול להיות כתובת אימייל או המחרוזת sub, ששווה למזהה Google של המשתמש. |
prompt |
string |
אופציונלי | רשימה של ערכי מחרוזות שמופרדים באמצעות רווחים, שמציינת אם שרת ההרשאות מבקש מהמשתמש לאמת מחדש את הזהות שלו ולתת הסכמה. ערכים אפשריים: none (ללא ממשק משתמש), consent (בקשת הסכמה), select_account (בקשה לבחירת חשבון). |
hl |
string |
אופציונלי | תג שפה BCP 47 שמשמש לציון שפת התצוגה במסכי הכניסה, בחלון לבחירת החשבון ובמסכי בקשת ההסכמה. לא מומלץ להשתמש בפרמטר הזה, כי הגדרות הדפדפן והעדפות חשבון Google הן בדרך כלל אינדיקטורים טובים יותר להעדפות השפה של המשתמש. |
include_granted_scopes |
boolean |
אופציונלי | אם הפרמטר הזה מסופק עם הערך true, ובקשת ההרשאה מאושרת, ההרשאה תכלול את כל ההרשאות הקודמות שניתנו לשילוב הזה של משתמש/אפליקציה עבור היקפי הרשאות אחרים. מידע נוסף זמין במאמר בנושא הרשאות מצטברות. |
claims |
object |
אופציונלי | הפרמטר claims משמש לציון שדה אופציונלי אחד או יותר שייכללו בתגובת UserInfo או באסימון המזהה. כדי לבקש את התלונה auth_time, משתמשים בclaims={\"id_token\":{\"auth_time\":{\"essential\":true}}}. |
פרמטרים של תגובה
תשובת ההרשאה מועברת לכתובת ה-URI להפניה אוטומטית של הלקוח (redirect_uri) באמצעות הפניה אוטומטית מסוג HTTP GET. פרמטרי התגובה מצורפים לכתובת ה-URI להפניה אוטומטית במחרוזת השאילתה או בפרגמנט ה-URL, בהתאם ל-response_type ול-response_mode.
| פרמטר | סוג | תיאור |
|---|---|---|
iss |
string |
מזהה המוסד המנפיק. לפי RFC 9207, הפרמטר הזה תמיד מוחזר ומוגדר לערך https://accounts.google.com. |
code |
string |
קוד ההרשאה שאפשר להחליף באסימון גישה ובאסימון מזהה. |
state |
string |
אותו ערך כמו הפרמטר state מהבקשה. |
id_token |
string |
אסימון JSON Web Token (JWT) שמכיל פרטי זהות של המשתמש. |
access_token |
string |
אסימון הגישה שאפשר לשלוח לממשק API של Google. |
token_type |
string |
סוג הטוקן שמוחזר. תמיד Bearer. |
expires_in |
integer |
משך החיים של אסימון הגישה בשניות, ביחס לזמן שבו הונפק האסימון. |
scope |
string |
היקפי הגישה שניתנו על ידי code או access_token, שמוצגים כרשימה של מחרוזות שמופרדות באמצעות רווחים ורגישות לאותיות רישיות. |
error |
string |
קוד שגיאה אם הבקשה נכשלה. |
error_description |
string |
תיאור השגיאה אם הבקשה נכשלה. |
תשובות שגיאה
בנקודת הקצה של ההרשאה, השגיאות מוחזרות ללקוחredirect_uri כפרמטרים במחרוזת השאילתה או בפרגמנט URL, או מוצגות למשתמש כדף שגיאה שמתארח ב-Google.
שגיאות של הפניה לכתובת אחרת
יכול להיות שהמערכת תחזיר את קודי השגיאה הבאים אל redirect_uri:
| שגיאה | תיאור |
|---|---|
access_denied |
המשתמש או שרת ההרשאות דחו את הבקשה. |
invalid_request |
חסר פרמטר חובה בבקשה, הבקשה כוללת ערך פרמטר לא תקין, הבקשה כוללת פרמטר יותר מפעם אחת או שהפורמט שלה שגוי. |
unauthorized_client |
ללקוח אין הרשאה לבקש קוד הרשאה באמצעות השיטה הזו. |
unsupported_response_type |
שרת ההרשאות לא תומך בהשגת קוד הרשאה באמצעות השיטה הזו. |
invalid_scope |
ההיקף המבוקש לא תקין, לא ידוע או שהפורמט שלו שגוי. |
שגיאות שגלויות למשתמשים
במקרים מסוימים, למשל אם client_id או redirect_uri לא תקינים, שרת ההרשאות לא יכול להפנות את המשתמש בחזרה לאפליקציה בצורה בטוחה.
במקרים כאלה, מוצג למשתמש ישירות דף שגיאה.
| שגיאה | תיאור |
|---|---|
admin_policy_enforced |
חשבון Google לא יכול לאשר היקף אחד או יותר מההיקפים המבוקשים בגלל המדיניות של האדמין ב-Google Workspace. מידע נוסף על האופן שבו אדמין ב-Google Workspace יכול להגביל את הגישה עד למתן הרשאה מפורשת למזהה לקוח OAuth זמין במאמר Google Workspace Admin help. |
disallowed_useragent |
נקודת הקצה של ההרשאה מוצגת בתוך סוכן משתמש מוטמע שאסור לשימוש על פי מדיניות OAuth 2.0 של Google. |
org_internal |
מזהה הלקוח ב-OAuth בבקשה הוא חלק מפרויקט שמגביל את הגישה לחשבונות Google בארגון ספציפי ב-Google Cloud. |
deleted_client |
לקוח ה-OAuth שמשמש לשליחת הבקשה נמחק. המחיקה יכולה להתבצע באופן ידני או אוטומטי במקרה של לקוחות שלא נעשה בהם שימוש. |
invalid_grant |
הפרמטר code_challenge לא תקין או חסר כשמשתמשים ב-PKCE. כשמרעננים טוקן גישה או משתמשים בהרשאה מצטברת, יכול להיות שתוקף הטוקן פג, שהוא בוטל או שחשבון המשתמש נמחק או הושבת. |
redirect_uri_mismatch |
הפרמטר redirect_uri שמועבר בבקשה לא תואם לכתובת ה-URI המורשית להפניה אוטומטית של מזהה הלקוח. בודקים את כתובות ה-URI המורשות להפניה אוטומטית במסוף Google Cloud. השגיאה הזו עשויה להתרחש גם אם הבקשה משתמשת בתהליך OAuth מחוץ לפס (OOB) שהוצא משימוש. |
invalid_client |
המקור שממנו נשלחה הבקשה לא מורשה ללקוח הזה, הגדרת הלקוח שגויה או סוד הלקוח של OAuth שגוי. |
origin_mismatch |
הסכימה, הדומיין או היציאה של ה-JavaScript שממנו יוצאת בקשת ההרשאה לא תואמים ל-URI של מקור JavaScript מורשה שרשום עבור מזהה לקוח OAuth. בודקים את המקורות המורשים של JavaScript במסוף Google Cloud. |
invalid_request |
משהו השתבש בבקשה. הסיבה לכך יכולה להיות בקשה לא תקינה, פרמטרים נדרשים שחסרים או שימוש בשיטת הרשאה ש-Google לא תומכת בה. |
Token Endpoint
נקודת הקצה של האסימון משמשת להחלפת קוד אימות באסימון גישה ובאסימון מזהה.
כתובת ה-URL: https://oauth2.googleapis.com/token
שיטת בקשה נתמכת: POST
פרמטרים של בקשה (Authorization Code Grant)
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
code |
string |
חובה | קוד ההרשאה שהתקבל מנקודת הקצה להרשאה. |
client_id |
string |
חובה | מזהה הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
client_secret |
string |
חובה | סוד הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
redirect_uri |
string |
חובה | כתובת ה-URI להפניה אוטומטית שמשמשת בבקשת ההרשאה הראשונית. כתובות ה-URI להפניה אוטומטית ומקורות ה-JavaScript המורשים צריכים לעמוד בכללי האימות שמפורטים במסמכי התיעוד בנושא אימות כתובות URI ב-OAuth 2.0. |
grant_type |
string |
חובה | הערך חייב להיות authorization_code. |
פרמטרים של בקשה (תהליך הרשאה למכשיר)
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
client_id |
string |
חובה | מזהה הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
client_secret |
string |
חובה | סוד הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
device_code |
string |
חובה | ה-device_code שמוחזר מנקודת הקצה של הרשאת המכשיר. |
grant_type |
string |
חובה | הערך חייב להיות urn:ietf:params:oauth:grant-type:device_code. |
פרמטרים של בקשה (רענון של טוקן גישה)
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
client_id |
string |
חובה | מזהה הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
client_secret |
string |
חובה | סוד הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
grant_type |
string |
חובה | צריך להגדיר את הערך refresh_token, כפי שמוגדר במפרט OpenID Connect Refresh Tokens. |
refresh_token |
string |
חובה | טוקן הרענון שמוחזר מהחלפת קוד ההרשאה. |
scope |
string |
אופציונלי | רשימה של היקפי הרשאות שמופרדים ברווחים, שנדרשים לטוקן הגישה החדש. ההיקפים המבוקשים צריכים להיות תת-קבוצה של ההיקפים שהוענקו בבקשת ההרשאה המקורית. |
גוף התשובה
שדות התגובה מוחזרים באובייקט JSON בגוף של תגובת ה-HTTP לבקשת POST של השולח אל https://oauth2.googleapis.com/token.
| שדה | סוג | תיאור |
|---|---|---|
access_token |
string |
אסימון הגישה שאפשר לשלוח לממשק API של Google. |
expires_in |
integer |
משך החיים של אסימון הגישה בשניות, ביחס לזמן שבו הונפק האסימון. |
id_token |
string |
אסימון JSON Web Token (JWT) שמכיל פרטי זהות של המשתמש. הטוקן הזה מוחזר במהלך ההחלפה הראשונית של קוד ההרשאה, ויכול להיות שיוחזר גם במהלך בקשה לטוקן רענון אם ניתן היקף ההרשאות openid. |
scope |
string |
היקפי הגישה שניתנו על ידי access_token, מוצגים כרשימה של מחרוזות שמופרדות ברווחים ותלויות באותיות רישיות. |
token_type |
string |
סוג הטוקן שמוחזר. תמיד Bearer. |
refresh_token |
string |
(אופציונלי) טוקן שאפשר להשתמש בו כדי לקבל טוקנים חדשים של גישה. השדה הזה מוחזר רק בהחלפה הראשונית של קוד הרשאה אם נשלחה בקשה ל-access_type=offline. |
refresh_token_expires_in |
integer |
(אופציונלי) משך החיים שנותר של אסימון הרענון בשניות. הערך הזה מוגדר רק כשהמשתמש מעניק גישה מוגבלת בזמן. |
תגובות שגיאה
אם הבקשה נכשלת, שרת ההרשאות מחזיר אובייקט JSON עם השדות הבאים:
| שדה | סוג | תיאור |
|---|---|---|
error |
string |
קוד שגיאה. |
error_description |
string |
תיאור השגיאה אם הבקשה נכשלה. |
בטבלה הבאה מפורטים קודי השגיאות האפשריים וקודי הסטטוס של HTTP שמשויכים אליהם:
| שגיאה | קוד סטטוס של HTTP | תיאור |
|---|---|---|
invalid_request |
400 |
חסר פרמטר חובה בבקשה, הבקשה כוללת ערך פרמטר לא תקין או שהפורמט שלה שגוי. |
invalid_client |
401 |
אימות הלקוח נכשל. לדוגמה, הערך של client_id או client_secret לא תקין, או שסוג הלקוח שגוי. |
invalid_grant |
400 |
קוד ההרשאה, טוקן הרענון או קוד המכשיר שצוינו לא תקינים, פג תוקפם, הם בוטלו או שהם לא תואמים ל-URI להפניה אוטומטית שנעשה בו שימוש בבקשת ההרשאה. |
unauthorized_client |
400 |
ללקוח המאומת אין הרשאה להשתמש בסוג ההרשאה הזה. |
unsupported_grant_type |
400 |
שרת ההרשאות לא תומך בסוג מענק ההרשאה. |
invalid_scope |
400 |
ההיקף המבוקש לא תקין, לא ידוע או שהפורמט שלו שגוי. |
authorization_pending |
428 |
(תהליך הרשאה במכשיר) המשתמש עדיין לא השלים את תהליך ההרשאה. |
slow_down |
429 |
(תהליך הרשמה למכשיר) המכשיר שולח בקשות סקר בתדירות גבוהה מדי. |
access_denied |
403 |
(תהליך הרשאה במכשיר) המשתמש סירב להעניק גישה למכשיר. |
expired_token |
400 |
(תהליך הרשמה למכשיר) התוקף של device_code פג. |
admin_policy_enforced |
400 |
המשתמש לא יכול לאשר את היקפי ההרשאות המבוקשים בגלל מדיניות שאוכפת האדמין ב-Google Workspace. |
org_internal |
403 |
מזהה הלקוח הוא חלק מפרויקט שמגביל את הגישה לארגון ספציפי ב-Google Cloud. |
נקודת קצה להרשאת מכשיר
נקודת הקצה של הרשאת המכשיר משמשת בתהליך הרשאת המכשיר ב-OAuth 2.0 כדי לקבל קוד משתמש וכתובת URL לאימות עבור מכשירים עם יכולות קלט מוגבלות.
כתובת ה-URL: https://oauth2.googleapis.com/device/code
שיטת בקשה נתמכת: POST
פרמטרים של בקשה
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
client_id |
string |
חובה | מזהה הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
scope |
string |
חובה | רשימה של היקפי הרשאות שמופרדים באמצעות רווחים ומזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. |
גוף התשובה
התגובה היא אובייקט JSON שמכיל את השדות הבאים:
| שדה | סוג | תיאור |
|---|---|---|
device_code |
string |
ערך ש-Google מקצה באופן ייחודי כדי לזהות את המכשיר שבו פועלת האפליקציה שמבקשת הרשאה. |
user_code |
string |
ערך תלוי-אותיות רישיות שמזהה עבור Google את היקפי ההרשאות שהאפליקציה מבקשת גישה אליהם. ממשק המשתמש ידריך את המשתמש להזין את הערך הזה במכשיר נפרד עם יכולות קלט עשירות יותר. |
verification_url |
string |
כתובת URL שהמשתמש צריך לנווט אליה במכשיר נפרד כדי להזין את user_code ולאשר או לדחות את הגישה לאפליקציה. |
expires_in |
integer |
משך הזמן בשניות שבו device_code ו-user_code תקפים. |
interval |
integer |
משך הזמן, בשניות, שהמכשיר צריך להמתין בין בקשות סקר. |
נקודת קצה לביטול
נקודת הקצה לביטול מאפשרת לאפליקציה לבטל אסימון גישה או אסימון רענון.
כתובת ה-URL: https://oauth2.googleapis.com/revoke
שיטת בקשה נתמכת: POST
פרמטרים של בקשה
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
token |
string |
חובה | אסימון הגישה או אסימון הרענון שרוצים לבטל. |
גוף התשובה
אם הביטול יתבצע בלי בעיות, התגובה תהיה HTTP 200 OK ריק. אם הביטול נכשל, מוחזרת תגובת שגיאה באובייקט JSON.
| שדה | סוג | תיאור |
|---|---|---|
error |
string |
קוד שגיאה אם הבקשה נכשלה. |
error_description |
string |
תיאור השגיאה אם הבקשה נכשלה. |
בטבלה הבאה מתוארים קודי השגיאות האפשריים:
| שגיאה | תיאור |
|---|---|
invalid_token |
פג התוקף של הטוקן שסופק בבקשה או שהוא כבר בוטל. |
invalid_request |
חסר פרמטר חובה בבקשה, הבקשה כוללת ערך פרמטר לא תקין או שהפורמט שלה שגוי. |
נקודת קצה של UserInfo
נקודת הקצה UserInfo מחזירה מידע על הפרופיל של המשתמש המאומת.
כתובת ה-URL: https://openidconnect.googleapis.com/v1/userinfo
שיטות בקשה נתמכות: GET, POST
כותרות של בקשות
| כותרת | תיאור |
|---|---|
Authorization |
חובה. הערך חייב להיות Bearer: access_token. |
גוף התשובה
שדות התגובה מוחזרים באובייקט JSON בגוף של תגובת ה-HTTP לבקשת GET או POST של השולח אל https://openidconnect.googleapis.com/v1/userinfo.
| שדה | סוג | תיאור |
|---|---|---|
sub |
string |
חובה. מזהה של המשתמש, ייחודי בין כל חשבונות Google ואי אפשר לעשות בו שימוש חוזר. מחרוזת שרגישה לאותיות רישיות, באורך של עד 255 תווים. |
name |
string |
השם המלא של המשתמש, בפורמט שניתן להצגה. |
given_name |
string |
השם הפרטי של המשתמש. |
family_name |
string |
שם המשפחה של המשתמש. |
picture |
string |
כתובת ה-URL של תמונת הפרופיל של המשתמש. |
email |
string |
כתובת האימייל של המשתמש. |
email_verified |
boolean |
האם כתובת האימייל של המשתמש אומתה. |
hd |
string |
הדומיין המתארח שמשויך לארגון Google Workspace או Cloud של המשתמש. |
נקודת קצה של פרטי טוקן
נקודת הקצה tokeninfo היא הטמעה ספציפית ל-Google שמשמשת לאימות של אסימון מזהה למטרות ניפוי באגים.
כתובת ה-URL: https://oauth2.googleapis.com/tokeninfo
שיטות בקשה נתמכות: GET, POST
פרמטרים של בקשה
| פרמטר | סוג | נדרש | תיאור |
|---|---|---|---|
id_token |
string |
חובה | אסימון המזהה לאימות. |
גוף התשובה
שדות התגובה מוחזרים באובייקט JSON בגוף של תגובת ה-HTTP לבקשת GET או POST של השולח אל https://oauth2.googleapis.com/tokeninfo.
| שדה | סוג | תיאור |
|---|---|---|
iss |
string |
מזהה המוסד המנפיק. תמיד https://accounts.google.com. |
sub |
string |
מזהה של המשתמש, ייחודי בין כל חשבונות Google ואי אפשר לעשות בו שימוש חוזר. |
aud |
string |
הקהל שאליו מיועד האסימון המזהה. זהו מזהה הלקוח של האפליקציה, שמתקבל ממסוף Google Cloud. |
iat |
integer |
הזמן שבו הונפק ה-JWT. הערך מיוצג כמספר השניות מאז 1970-01-01T0:0:0Z, כפי שנמדד ב-UTC. |
exp |
integer |
תאריך התפוגה שעד אליו או אחריו אסור לקבל את טוקן המזהה לעיבוד. הערך מיוצג כמספר השניות מאז 1970-01-01T0:0:0Z, כפי שנמדד ב-UTC. |
email |
string |
כתובת האימייל של המשתמש. |
email_verified |
string |
האם כתובת האימייל של המשתמש אומתה. הערך הוא מחרוזת "true" או "false". |
access_type |
string |
סוג הגישה שנדרש בבקשת ההרשאה המקורית. |
azp |
string |
מזהה הלקוח של המציג המורשה, שמתקבל ממסוף Google Cloud. |
scope |
string |
רשימה של היקפי הרשאות שהוקצו לטוקן, מופרדים ברווחים. |
alg |
string |
האלגוריתם שמשמש לחתימה על טוקן ה-ID. |
kid |
string |
מזהה המפתח שמשמש לחתימה על טוקן הזהות. |
typ |
string |
סוג האסימון. תמיד JWT. |