ספריית JavaScript לאימות על ידי צד שלישי של Google לאתרים – הפניית API

בחומר עזר זה מתואר Google 3P Authorization JavaScript Library API שבהם אפשר להשתמש כדי לטעון קודי הרשאה או אסימוני גישה מ-Google.

שיטה: google.accounts.oauth2.initCodeClient

ה-method initCodeClient מאתחלת ומחזירה לקוח קוד, עם את התצורה של הפרמטר.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

סוג הנתונים: CodeClientConfig

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים CodeClientConfig.

מאפיינים
client_id חובה. מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה במסוף API.
scope חובה. רשימה מופרדת ברווחים של היקפים שמזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה משפיעים על מסך ההסכמה ש-Google מציגה למשתמש.
include_granted_scopes אופציונלי. ברירת המחדל היא true. מאפשר לאפליקציות להשתמש בנתונים מצטברים הרשאה לבקש גישה להיקפים נוספים בהקשר. אם מגדירים ערך הפרמטר הזה ל-false ובקשת ההרשאה אושרה, ולאחר מכן אסימון הגישה החדש יכסה רק את כל היקפי ההרשאות שנדרשים על ידי scope בCodeClientConfig הזה.
redirect_uri נדרש עבור הפניה אוטומטית של חוויית המשתמש. קובע את המיקום שאליו שרת ה-API מפנה את המשתמש לכתובת אחרת אחרי שהמשתמש משלים את תהליך ההרשאה. הערך צריך להתאים בדיוק לאחד ממזהי ה-URI המורשים להפניה אוטומטית עבור לקוח OAuth 2.0, שאותו הגדרת במסוף ה-API, וחייב להתאים לכללי האימות של כתובות URI להפניה אוטומטית. ממשק המשתמש הקופץ יתעלם מהנכס.
callback נדרש עבור חלון קופץ של UX. פונקציית ה-JavaScript שמטפלת בתגובת קוד שמוחזרת. ה-UX בהפניה לכתובת אחרת יתעלם מהנכס.
state זה שינוי אופציונלי. מומלץ עבור הפניה אוטומטית של חוויית המשתמש. מציינת כל ערך מחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאות.
enable_granular_consent אופציונלי. ברירת המחדל היא true. אם המדיניות מוגדרת לערך false, הרשאות מפורטות יותר בחשבון Google תושבת עבור מזהי לקוחות OAuth שנוצרו לפני 2019. אם מגדירים גם enable_granular_consent וגם enable_serial_consent, רק enable_granular_consent יכנס לתוקף, והמערכת תתעלם מהערך enable_serial_consent.

אין השפעה על מזהי לקוחות חדשים ב-OAuth, כי הרשאות מפורטות יותר תמיד מופעלות לגביהם.
enable_serial_consent הוצא משימוש. במקומו צריך להשתמש ברכיב enable_granular_consent. הזה יש אותה השפעה כמו enable_granular_consent. אפליקציות קיימות משתמשים ב-enable_serial_consent יכולים להמשיך לעשות זאת, אבל מומלץ לעדכן את הקוד כך שישתמש ב-enable_granular_consent לעדכון הבא של האפליקציה שלכם.
login_hint זה שינוי אופציונלי. אם האפליקציה מזהה את המשתמש שצריך לאשר את הבקשה, היא יכולה להשתמש במאפיין הזה כדי לספק ל-Google רמז להתחברות. בסיום התהליך, המערכת תדלג על בחירת החשבון. הערך בשדה sub של כתובת האימייל או של האסימון המזהה של משתמש היעד. מידע נוסף זמין בשדה login_hint במסמכי התיעוד של OpenID Connect.
hd זה שינוי אופציונלי. אם האפליקציה מזהה את הדומיין ב-Workspace שאליו המשתמש שייך, אפשר להשתמש בו כדי לתת ל-Google רמז. כשתהליך הפעולה הסתיים בהצלחה, חשבונות המשתמש מוגבלים לדומיין שצוין או נבחרים מראש עבורו. מידע נוסף זמין בשדה hd במסמכי התיעוד של OpenID Connect.
ux_mode זה שינוי אופציונלי. מצב ה-UX לשימוש בתהליך ההרשאה. כברירת מחדל, תהליך ההסכמה ייפתח בחלון קופץ. הערכים החוקיים הם popup ו-redirect.
select_account אופציונלי. ברירת המחדל היא false. ערך בוליאני שיבקש מהמשתמש לבחור חשבון.
error_callback זה שינוי אופציונלי. פונקציית JavaScript שמטפלת בשגיאות שאינן מסוג OAuth, כמו פתיחת החלון הקופץ נכשלה; או נסגרת לפני תגובת OAuth הוחזרו.

בשדה 'type' של פרמטר הקלט מוצגת הסיבה המפורטת.
  • popup_failed_to_open פתיחת החלון הקופץ נכשלה.
  • popup_closed החלון הקופץ נסגר לפני אישור OAuth התשובה תוחזר.
  • Placeholder לא ידוע לשגיאות אחרות.

סוג הנתונים: CodeClient

למחלקה יש רק אפשרות בקשה של שיטה ציבורית אחת, שמתחילה את OAuth 2.0 תהליך UX.

interface CodeClient {
  requestCode(): void;
}

סוג הנתונים: CodeResponse

אובייקט JavaScript CodeResponse יועבר ל-method callback ב- בחלון הקופץ של חוויית המשתמש. בחוויית המשתמש בהפניה לכתובת אחרת, השדה CodeResponse יועבר בתור כתובת URL .

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים CodeResponse.

מאפיינים
code קוד ההרשאה של תגובת אסימון מוצלחת.
scope רשימה מופרדת ברווחים של היקפים שאושרו על ידי המשתמש.
state ערך המחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה.
error קוד שגיאת ASCII יחיד.
error_description טקסט ASCII קריא לאנשים שמספק מידע נוסף, שמשמש למפתחים של הלקוח להבין את השגיאה שאירעה.
error_uri URI שמזהה דף אינטרנט קריא לאנשים עם מידע על השגיאה. המזהה הזה משמש כדי לספק למפתח הלקוח מידע נוסף על השגיאה.

שיטה: google.accounts.oauth2.initTokenClient

ה-method initTokenClient מאתחלת ומחזירה לקוח אסימון, עם הפרמטר את התצורה של הפרמטר.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

סוג הנתונים: TokenClientConfig

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים TokenClientConfig.

מאפיינים
client_id חובה. מזהה הלקוח של האפליקציה. אפשר למצוא את הערך הזה במסוף API.
callback חובה. פונקציית ה-JavaScript שמטפלת בתגובה של אסימון שהוחזר.
scope חובה. רשימה מופרדת ברווחים של היקפים שמזהים את המשאבים שהאפליקציה יכולה לגשת אליהם בשם המשתמש. הערכים האלה משפיעים על מסך ההסכמה ש-Google מציגה למשתמש.
include_granted_scopes אופציונלי. ברירת המחדל היא true. מאפשר לאפליקציות להשתמש בנתונים מצטברים הרשאה לבקש גישה להיקפים נוספים בהקשר. אם מגדירים ערך הפרמטר הזה ל-false ובקשת ההרשאה אושרה, ולאחר מכן אסימון הגישה החדש יכסה רק את כל היקפי ההרשאות שנדרשים על ידי scope בTokenClientConfig הזה.
prompt אופציונלי. ברירת המחדל היא 'select_account'. קובץ שמופרד ברווחים, רשימה תלוית אותיות רישיות של הנחיות להצגת המשתמש. הערכים האפשריים הם:
  • Empty string המשתמש יתבקש רק בפעם הראשונה שהאפליקציה תבקש גישה. אין אפשרות לציין את הערך הזה בערכים אחרים.
  • none: אין להציג מסכי אימות או הסכמה. אין לציין אותו בערכים אחרים.
  • 'consent': הצגת בקשת הסכמה למשתמש.
  • 'select_account' הצגת בקשה מהמשתמש לבחור חשבון.
enable_granular_consent אופציונלי. ברירת המחדל היא true. אם המדיניות מוגדרת לערך false, הרשאות מפורטות יותר בחשבון Google תושבת עבור מזהי לקוחות OAuth שנוצרו לפני 2019. אם מגדירים גם enable_granular_consent וגם enable_serial_consent, רק enable_granular_consent יכנס לתוקף, והמערכת תתעלם מהערך enable_serial_consent.

אין השפעה על מזהי לקוחות חדשים ב-OAuth, כי הרשאות מפורטות יותר תמיד מופעלות לגביהם.
enable_serial_consent הוצא משימוש. במקומו צריך להשתמש ברכיב enable_granular_consent. הזה יש אותה השפעה כמו enable_granular_consent. אפליקציות קיימות משתמשים ב-enable_serial_consent יכולים להמשיך לעשות זאת, אבל מומלץ לעדכן את הקוד כך שישתמש ב-enable_granular_consent לעדכון הבא של האפליקציה שלכם.
login_hint זה שינוי אופציונלי. אם האפליקציה מזהה את המשתמש שצריך לאשר את הבקשה, היא יכולה להשתמש במאפיין הזה כדי לספק ל-Google רמז להתחברות. בסיום התהליך, המערכת תדלג על בחירת החשבון. הערך בשדה sub של כתובת האימייל או של האסימון המזהה של משתמש היעד. מידע נוסף זמין בשדה login_hint במסמכי התיעוד של OpenID Connect.
hd זה שינוי אופציונלי. אם האפליקציה מזהה את הדומיין ב-Workspace שאליו המשתמש שייך, אפשר להשתמש בו כדי לתת ל-Google רמז. כשתהליך הפעולה הסתיים בהצלחה, חשבונות המשתמש מוגבלים לדומיין שצוין או נבחרים מראש עבורו. מידע נוסף זמין בשדה hd במסמכי התיעוד של OpenID Connect.
state זה שינוי אופציונלי. לא מומלץ. מציינת כל ערך מחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאות.
error_callback זה שינוי אופציונלי. פונקציית JavaScript שמטפלת בשגיאות שאינן מסוג OAuth, כמו פתיחת החלון הקופץ נכשלה. או נסגרת לפני תגובת OAuth הוחזרו.

בשדה 'type' של פרמטר הקלט מוצגת הסיבה המפורטת.
  • popup_failed_to_open פתיחת החלון הקופץ נכשלה.
  • popup_closed החלון הקופץ נסגר לפני אישור OAuth התשובה תוחזר.
  • Placeholder לא ידוע לשגיאות אחרות.

סוג הנתונים: TokenClient

לכיתה יש רק שיטה ציבורית אחת requestAccessToken, שמתחילה את תהליך UX ב-OAuth 2.0 Token UX.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
ארגומנטים
overrideConfig OverridableTokenClientConfig זה שינוי אופציונלי. ההגדרות שרוצים לשנות בשיטה הזו.

סוג הנתונים: OverridableTokenClientConfig

בטבלה הבאה מפורטים המאפיינים של OverridableTokenClientConfig סוג הנתונים.

מאפיינים
scope זה שינוי אופציונלי. רשימה מופרדת ברווחים של היקפים מזהים את המשאבים שהאפליקציה שלך יכולה לגשת אליה בשם המשתמש. הערכים האלה הודעה על מסך ההסכמה ש-Google מציגה למשתמש.
include_granted_scopes אופציונלי. ברירת המחדל היא true. מאפשר לאפליקציות להשתמש בנתונים מצטברים הרשאה לבקש גישה להיקפים נוספים בהקשר. אם מגדירים ערך הפרמטר הזה ל-false ובקשת ההרשאה אושרה, ולאחר מכן אסימון הגישה החדש יכסה רק את כל היקפי ההרשאות שנדרשים על ידי scope בOverridableTokenClientConfig הזה.
prompt זה שינוי אופציונלי. רשימת הנחיות להצגת המשתמש, שמופרדות ברווחים, תלויות אותיות רישיות.
enable_granular_consent אופציונלי. ברירת המחדל היא true. אם המדיניות מוגדרת לערך false, הרשאות מפורטות יותר בחשבון Google תושבת עבור מזהי לקוח OAuth שנוצרו לפני 2019.אם מגדירים גם enable_granular_consent וגם enable_serial_consent, רק enable_granular_consent יכנס לתוקף והמערכת תתעלם מערך אחד (enable_serial_consent).

אין השפעה על מזהי לקוחות חדשים ב-OAuth, כי הרשאות מפורטות יותר תמיד מופעלות לגביהם.
enable_serial_consent הוצא משימוש. במקומו צריך להשתמש ברכיב enable_granular_consent. הזה יש אותה השפעה כמו enable_granular_consent. אפליקציות קיימות משתמשים ב-enable_serial_consent יכולים להמשיך לעשות זאת, אבל מומלץ לעדכן את הקוד כך שישתמש ב-enable_granular_consent לעדכון הבא של האפליקציה שלכם.
login_hint זה שינוי אופציונלי. אם האפליקציה מזהה את המשתמש שצריך לאשר את הבקשה, היא יכולה להשתמש במאפיין הזה כדי לספק ל-Google רמז להתחברות. בסיום התהליך, המערכת תדלג על בחירת החשבון. הערך בשדה sub של כתובת האימייל או של האסימון המזהה של משתמש היעד. מידע נוסף זמין בשדה login_hint במסמכי התיעוד של OpenID Connect.
state זה שינוי אופציונלי. לא מומלץ. מציינת כל ערך מחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה של שרת ההרשאות.

סוג הנתונים: TokenResponse

אובייקט JavaScript מסוג TokenResponse יועבר לשיטת הקריאה החוזרת ב- בחלון הקופץ של חוויית המשתמש.

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים TokenResponse.

מאפיינים
access_token אסימון הגישה לתגובה מוצלחת של אסימון.
expires_in משך החיים בשניות של אסימון הגישה.
hd הדומיין המתארח שאליו שייך המשתמש המחובר.
prompt הערך של ההנחיה שנעשה בו שימוש מרשימת הערכים האפשריים שצוינו על ידי TokenClientConfig או על ידי OverridableTokenClientConfig.
token_type סוג האסימון שהונפק.
scope רשימה מופרדת ברווחים של היקפים שאושרו על ידי המשתמש.
state ערך המחרוזת שבו האפליקציה משתמשת כדי לשמור על המצב בין בקשת ההרשאה לבין התגובה.
error קוד שגיאת ASCII יחיד.
error_description טקסט ASCII קריא לאנשים שמספק מידע נוסף, שמשמש למפתחים של הלקוח להבין את השגיאה שאירעה.
error_uri URI שמזהה דף אינטרנט קריא לאנשים עם מידע על השגיאה. המזהה הזה משמש כדי לספק למפתח הלקוח מידע נוסף על השגיאה.

שיטה: google.accounts.oauth2.hasGrantedAllScopes

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

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
ארגומנטים
tokenResponse TokenResponse חובה. TokenResponse לאובייקט.
firstScope מחרוזת חובה. ההיקף שצריך לבדוק.
restScopes String[] זה שינוי אופציונלי. היקפים אחרים שצריך לבדוק.
החזרות
בוליאני הערך הוא True אם כל ההיקפים ניתנים.

שיטה: google.accounts.oauth2.hasGrantedAnyScope

הפונקציה בודקת אם המשתמש העניק אחד מהיקפי ההרשאות או מהיקפי ההרשאות שצוינו.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
ארגומנטים
tokenResponse TokenResponse חובה. TokenResponse לאובייקט.
firstScope מחרוזת חובה. ההיקף שצריך לבדוק.
restScopes String[] זה שינוי אופציונלי. היקפים אחרים שצריך לבדוק.
החזרות
בוליאני הערך הוא True אם אחד מהיקפי ההרשאות הוענקו.

שיטה: google.accounts.oauth2.revoke

השיטה revoke מבטלת את כל היקפי ההרשאות שהמשתמש העניק לאפליקציה. כדי לבטל את ההרשאה צריך אסימון גישה תקין.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
ארגומנטים
accessToken מחרוזת חובה. אסימון גישה חוקי.
callback פונקציה זה שינוי אופציונלי. ה-handler RevocationResponse.

סוג הנתונים: RevocationResponse

אובייקט JavaScript RevocationResponse יועבר לשיטת הקריאה החוזרת (callback).

בטבלה הבאה מפורטים המאפיינים של סוג הנתונים RevocationResponse.

מאפיינים
successful בוליאני. true בתאריך הצליחו, false נכשל.
error מחרוזת. לא מוגדר מהי הצלחה. קוד שגיאת ASCII יחיד. גישה זו כוללת, בין היתר, את פרוטוקול OAuth הרגיל קודי שגיאה 2.0. שגיאות נפוצות בשיטה revoke:
  • invalid_token – האסימון כבר פג או שהוא בוטל לפני קריאה לשיטה revoke. ברוב המקרים, אפשר להתייחס למענק שמשויך אל accessToken בוטל.
  • invalid_request – האסימון לא ניתן לביטול. עליך לוודא הכתובת accessToken היא פרטי כניסה תקינים מסוג OAuth 2.0 של Google.
error_description מחרוזת. לא מוגדר מהי הצלחה. טקסט ASCII קריא לאנשים מספק מידע נוסף על נכס error. מפתחים יכולים להשתמש במידע הזה כדי להבין טוב יותר לשגיאה שאירעה. המחרוזת error_description זמינה באנגלית בלבד. עבור השגיאות הנפוצות המפורטות ב-error, ערכי error_description התואמים הם:
  • invalid_token – האסימון פג או בוטל.
  • invalid_request – האסימון לא ניתן לביטול.