เอกสารอ้างอิงของ Google Account Authorization JavaScript API

เอกสารอ้างอิงนี้อธิบาย JavaScript API การให้สิทธิ์บัญชี Google ซึ่งใช้เพื่อรับรหัสการให้สิทธิ์หรือโทเค็นการเข้าถึงจาก Google

เมธอด: google.accounts.oauth2.initCodeClient

เมธอด initCodeClient จะเริ่มต้นและแสดงผลไคลเอ็นต์โค้ดที่มี การกำหนดค่าในพารามิเตอร์

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

ประเภทข้อมูล: CodeClientConfig

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล CodeClientConfig

พร็อพเพอร์ตี้
client_id ต้องระบุ รหัสไคลเอ็นต์สำหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน Google Cloud Console
scope ต้องระบุ รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันของคุณเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะแจ้งให้หน้าจอคำยินยอมที่ Google แสดงต่อผู้ใช้ทราบ
include_granted_scopes ไม่บังคับ ค่าเริ่มต้นคือ true ช่วยให้แอปพลิเคชันใช้การให้สิทธิ์ทีละส่วน เพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมตามบริบท หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และได้รับคำขอให้สิทธิ์ โทเค็นเพื่อการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ร้องขอ ใน CodeClientConfig นี้
redirect_uri ต้องระบุสำหรับ UX การเปลี่ยนเส้นทาง กำหนดว่าเซิร์ฟเวอร์ API จะเปลี่ยนเส้นทางผู้ใช้ไปที่ใด หลังจากที่ผู้ใช้ดำเนินการตามขั้นตอนการให้สิทธิ์เสร็จสมบูรณ์ ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสำหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกำหนดค่าใน Google Cloud Console และต้องเป็นไปตามกฎการตรวจสอบ URI การเปลี่ยนเส้นทาง เมื่อใช้ ux_mode: 'popup' ระบบจะไม่สนใจพารามิเตอร์นี้ และ redirect_uri จะมีค่าเริ่มต้นเป็นต้นทาง ของหน้าที่เรียกใช้ initCodeClient
callback ต้องระบุสำหรับ UX ป๊อปอัป ฟังก์ชัน JavaScript ที่จัดการการตอบกลับของโค้ดที่ส่งคืน UX การเปลี่ยนเส้นทางจะละเว้นพร็อพเพอร์ตี้นี้
state ไม่บังคับ แนะนำสำหรับ UX การเปลี่ยนเส้นทาง ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคำขอการให้สิทธิ์และการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์
enable_granular_consent เลิกใช้งานแล้ว จะไม่มีผลหากตั้งค่า ดูรายละเอียดเกี่ยวกับลักษณะการทำงานของความยินยอมได้ที่ สิทธิ์แบบละเอียด
enable_serial_consent เลิกใช้งานแล้ว จะไม่มีผลหากตั้งค่า ดูรายละเอียดเกี่ยวกับลักษณะการทำงานของความยินยอมได้ที่ สิทธิ์แบบละเอียด
login_hint ไม่บังคับ หากแอปพลิเคชันทราบว่าผู้ใช้รายใดควรให้สิทธิ์คำขอ ก็สามารถใช้พร็อพเพอร์ตี้นี้เพื่อระบุคำแนะนำในการเข้าสู่ระบบให้ Google หากสำเร็จ ระบบจะข้ามการเลือกบัญชี ค่าฟิลด์อีเมลหรือโทเค็นรหัส sub สำหรับผู้ใช้เป้าหมาย ดูข้อมูลเพิ่มเติมได้ที่ช่อง login_hint ในเอกสารประกอบ OpenID Connect
hd ไม่บังคับ หากแอปพลิเคชันทราบโดเมน Workspace ที่ผู้ใช้เป็นสมาชิก ให้ใช้โดเมนดังกล่าวเพื่อเป็นคำแนะนำแก่ Google เมื่อดำเนินการสำเร็จแล้ว บัญชีผู้ใช้จะจำกัดหรือเลือกไว้ล่วงหน้าสำหรับโดเมนที่ระบุ ดูข้อมูลเพิ่มเติมได้ที่ช่อง hd ในเอกสารประกอบ OpenID Connect
ux_mode ไม่บังคับ popup หรือ redirect ค่าเริ่มต้นคือ popup ควบคุมโหมด UX ที่ใช้สำหรับขั้นตอนรหัสการให้สิทธิ์ โดยใช้กล่องโต้ตอบป๊อปอัปในหน้าปัจจุบันหรือผ่านการเปลี่ยนเส้นทางแบบเต็มหน้า
select_account ไม่บังคับ ค่าเริ่มต้นคือ 'false' ค่าบูลีนเพื่อแจ้งให้ผู้ใช้เลือกบัญชี
error_callback ไม่บังคับ ฟังก์ชัน JavaScript ที่จัดการข้อผิดพลาดที่ไม่ใช่ OAuth บางอย่าง เช่น เปิดหน้าต่างป๊อปอัปไม่สำเร็จ หรือปิดก่อนที่จะมีการส่งคืนการตอบกลับ OAuth

ฟิลด์ `type` ของพารามิเตอร์อินพุตจะให้เหตุผลโดยละเอียด
  • popup_failed_to_open เปิดหน้าต่างป๊อปอัปไม่สำเร็จ
  • popup_closed หน้าต่างป๊อปอัปปิดก่อนที่จะมีการส่งคืนการตอบกลับ OAuth
  • ตัวยึดตำแหน่ง unknown สำหรับข้อผิดพลาดอื่นๆ

ประเภทข้อมูล: CodeClient

คลาสนี้มีเมธอดสาธารณะเพียงเมธอดเดียวคือ requestCode ซึ่งจะเริ่มโฟลว์ UX ของรหัส OAuth 2.0 

interface CodeClient {   requestCode(): void; }

ประเภทข้อมูล: CodeResponse

ระบบจะส่งออบเจ็กต์ CodeResponse JavaScript ไปยังเมธอด callback ใน UX ป๊อปอัป ใน UX การเปลี่ยนเส้นทาง ระบบจะส่ง CodeResponse เป็นพารามิเตอร์ URL

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล CodeResponse

พร็อพเพอร์ตี้
code รหัสการให้สิทธิ์ของการตอบกลับโทเค็นที่สำเร็จ
scope รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งผู้ใช้ได้อนุมัติ
state ค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคำขอการให้สิทธิ์และการตอบกลับ
error รหัสข้อผิดพลาด ASCII เดียว
error_description ข้อความ ASCII ที่มนุษย์อ่านได้ซึ่งให้ข้อมูลเพิ่มเติม ใช้เพื่อช่วยนักพัฒนาซอฟต์แวร์ไคลเอ็นต์ในการทำความเข้าใจข้อผิดพลาดที่เกิดขึ้น
error_uri URI ที่ระบุหน้าเว็บที่มนุษย์อ่านได้ซึ่งมีข้อมูลเกี่ยวกับข้อผิดพลาด ใช้เพื่อให้ข้อมูลเพิ่มเติมเกี่ยวกับข้อผิดพลาดแก่นักพัฒนาซอฟต์แวร์ไคลเอ็นต์

เมธอด: google.accounts.oauth2.initTokenClient

เมธอด initTokenClient จะเริ่มต้นและแสดงผลไคลเอ็นต์โทเค็นพร้อมการกำหนดค่าในพารามิเตอร์

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

ประเภทข้อมูล: TokenClientConfig

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล TokenClientConfig

พร็อพเพอร์ตี้
client_id ต้องระบุ รหัสไคลเอ็นต์สำหรับแอปพลิเคชัน คุณดูค่านี้ได้ใน Google Cloud Console
callback ต้องระบุ ฟังก์ชัน JavaScript ที่จัดการการตอบกลับโทเค็นที่ส่งคืน
scope ต้องระบุ รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากรที่แอปพลิเคชันของคุณเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้จะแจ้งให้หน้าจอคำยินยอมที่ Google แสดงต่อผู้ใช้ทราบ
include_granted_scopes ไม่บังคับ ค่าเริ่มต้นคือ true ช่วยให้แอปพลิเคชันใช้การให้สิทธิ์ทีละส่วน เพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมตามบริบท หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และได้รับคำขอให้สิทธิ์ โทเค็นเพื่อการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ร้องขอ ใน TokenClientConfig นี้
prompt ไม่บังคับ ค่าเริ่มต้นคือ 'select_account' รายการพรอมต์ที่คั่นด้วยช่องว่าง ซึ่งคำนึงถึงตัวพิมพ์เล็กและใหญ่เพื่อแสดงต่อผู้ใช้ ค่าที่เป็นไปได้มีดังนี้
  • สตริงว่าง ระบบจะแจ้งให้ผู้ใช้ทราบเฉพาะครั้งแรกที่แอปขอสิทธิ์เข้าถึง ระบุร่วมกับค่าอื่นๆ ไม่ได้
  • "ไม่มี" ไม่แสดงหน้าจอการตรวจสอบสิทธิ์หรือความยินยอมใดๆ ต้องไม่ระบุร่วมกับค่าอื่นๆ
  • "ยินยอม" แจ้งให้ผู้ใช้ให้ความยินยอม
  • 'select_account' แจ้งให้ผู้ใช้เลือกบัญชี
enable_granular_consent เลิกใช้งานแล้ว จะไม่มีผลหากตั้งค่า ดูรายละเอียดเกี่ยวกับลักษณะการทำงานของความยินยอมได้ที่ สิทธิ์แบบละเอียด
enable_serial_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
  • ตัวยึดตำแหน่ง unknown สำหรับข้อผิดพลาดอื่นๆ

ประเภทข้อมูล: TokenClient

คลาสนี้มีเมธอดสาธารณะเพียงเมธอดเดียว requestAccessToken ซึ่งจะเริ่มโฟลว์ UX ของโทเค็น OAuth 2.0

interface TokenClient {   requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void; }
อาร์กิวเมนต์
overrideConfig OverridableTokenClientConfig ไม่บังคับ การกำหนดค่าที่จะลบล้างในวิธีนี้

ประเภทข้อมูล: OverridableTokenClientConfig

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล OverridableTokenClientConfig

พร็อพเพอร์ตี้
scope ไม่บังคับ รายการขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุทรัพยากร ที่แอปพลิเคชันของคุณเข้าถึงได้ในนามของผู้ใช้ ค่าเหล่านี้ จะแจ้งให้หน้าจอคำยินยอมที่ Google แสดงต่อผู้ใช้ทราบ
include_granted_scopes ไม่บังคับ ค่าเริ่มต้นคือ true ช่วยให้แอปพลิเคชันใช้การให้สิทธิ์ทีละส่วน เพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมตามบริบท หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และได้รับคำขอให้สิทธิ์ โทเค็นเพื่อการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ร้องขอ ใน OverridableTokenClientConfig นี้
prompt ไม่บังคับ รายการพรอมต์ที่คั่นด้วยช่องว่างและคำนึงถึงตัวพิมพ์เล็กและใหญ่เพื่อแสดงต่อผู้ใช้
enable_granular_consent เลิกใช้งานแล้ว จะไม่มีผลหากตั้งค่า ดูรายละเอียดเกี่ยวกับลักษณะการทำงานของความยินยอมได้ที่ สิทธิ์แบบละเอียด
enable_serial_consent เลิกใช้งานแล้ว จะไม่มีผลหากตั้งค่า ดูรายละเอียดเกี่ยวกับลักษณะการทำงานของความยินยอมได้ที่ สิทธิ์แบบละเอียด
login_hint ไม่บังคับ หากแอปพลิเคชันทราบว่าผู้ใช้รายใดควรให้สิทธิ์คำขอ ก็สามารถใช้พร็อพเพอร์ตี้นี้เพื่อระบุคำแนะนำในการเข้าสู่ระบบให้ Google หากสำเร็จ ระบบจะข้ามการเลือกบัญชี ค่าฟิลด์อีเมลหรือโทเค็นรหัส sub สำหรับผู้ใช้เป้าหมาย ดูข้อมูลเพิ่มเติมได้ที่ช่อง login_hint ในเอกสารประกอบ OpenID Connect
state ไม่บังคับ ไม่แนะนำ ระบุค่าสตริงที่แอปพลิเคชันใช้เพื่อรักษาสถานะระหว่างคำขอการให้สิทธิ์และการตอบกลับของเซิร์ฟเวอร์การให้สิทธิ์

ประเภทข้อมูล: TokenResponse

ระบบจะส่งTokenResponseออบเจ็กต์ JavaScript ไปยังเมธอด Callback ใน UX ของป๊อปอัป

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล 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[] ไม่บังคับ ขอบเขตอื่นๆ ที่ต้องตรวจสอบ
การคืนสินค้า
บูลีน เป็นจริงหากได้รับสิทธิ์ขอบเขตทั้งหมด

เมธอด: google.accounts.oauth2.hasGrantedAnyScope

ตรวจสอบว่าผู้ใช้ให้สิทธิ์ขอบเขตที่ระบุหรือไม่

google.accounts.oauth2.hasGrantedAnyScope(                                            tokenResponse: TokenResponse,                                            firstScope: string, ...restScopes: string[]                                          ): boolean;
อาร์กิวเมนต์
tokenResponse TokenResponse ต้องระบุ ออบเจ็กต์ TokenResponse
firstScope สตริง ต้องระบุ ขอบเขตที่จะตรวจสอบ
restScopes string[] ไม่บังคับ ขอบเขตอื่นๆ ที่ต้องตรวจสอบ
การคืนสินค้า
บูลีน เป็นจริงหากมีการให้สิทธิ์ขอบเขตใดก็ตาม

Method: google.accounts.oauth2.revoke

เมธอด revoke จะเพิกถอนขอบเขตทั้งหมดที่ผู้ใช้ให้สิทธิ์แก่แอป ต้องมีโทเค็นเพื่อการเข้าถึงที่ถูกต้องจึงจะเพิกถอนสิทธิ์ได้

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
อาร์กิวเมนต์
accessToken สตริง ต้องระบุ โทเค็นเพื่อการเข้าถึงที่ถูกต้อง
callback ฟังก์ชัน ไม่บังคับ ตัวแฮนเดิล RevocationResponse

ประเภทข้อมูล: RevocationResponse

ระบบจะส่งRevocationResponseออบเจ็กต์ JavaScript ไปยังเมธอด Callback

ตารางต่อไปนี้แสดงรายการพร็อพเพอร์ตี้ของประเภทข้อมูล RevocationResponse

พร็อพเพอร์ตี้
successful บูลีน true เมื่อสำเร็จ false เมื่อไม่สำเร็จ
error สตริง ไม่กำหนดเมื่อสำเร็จ รหัสข้อผิดพลาด ASCII เดียว ซึ่งรวมถึงแต่ไม่จำกัดเพียงรหัสข้อผิดพลาด OAuth 2.0 มาตรฐาน ข้อผิดพลาดที่พบบ่อยสำหรับวิธี revoke
  • invalid_token - โทเค็นหมดอายุหรือถูกเพิกถอนก่อนที่จะเรียกใช้เมธอด revoke ในกรณีส่วนใหญ่ คุณจะถือว่าการให้สิทธิ์ที่เชื่อมโยงกับ accessToken ถูกเพิกถอนแล้ว
  • invalid_request - เพิกถอนโทเค็นไม่ได้ คุณควรตรวจสอบว่า accessToken เป็นข้อมูลเข้าสู่ระบบ Google OAuth 2.0 ที่ถูกต้อง
error_description สตริง ไม่กำหนดเมื่อสำเร็จ ข้อความ ASCII ที่มนุษย์อ่านได้จะให้ข้อมูลเพิ่มเติมเกี่ยวกับ error พร็อพเพอร์ตี้ นักพัฒนาแอปสามารถใช้ข้อมูลนี้เพื่อทำความเข้าใจ ข้อผิดพลาดที่เกิดขึ้นได้ดียิ่งขึ้น สตริง error_description จะเป็นภาษาอังกฤษเท่านั้น สำหรับข้อผิดพลาดที่พบบ่อยซึ่งแสดงในerrorerror_descriptionที่เกี่ยวข้อง ให้ทำดังนี้
  • invalid_token - โทเค็นหมดอายุหรือถูกเพิกถอน
  • invalid_request - เพิกถอนโทเค็นไม่ได้