ไลบรารี JavaScript การให้สิทธิ์ของบุคคลที่สามของ Google สำหรับเว็บไซต์ - การอ้างอิง API

ข้อมูลอ้างอิงนี้อธิบาย Google 3P Authorization JavaScript Library API ซึ่งคุณใช้โหลดรหัสการให้สิทธิ์หรือโทเค็นการเข้าถึงจาก Google ได้

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

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

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

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

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

พร็อพเพอร์ตี้
client_id	ต้องระบุ รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ในคอนโซล API
scope	ต้องระบุ รายการขอบเขตที่คั่นด้วยเว้นวรรคซึ่งระบุทรัพยากรที่แอปพลิเคชันของคุณเข้าถึงในนามของผู้ใช้ได้ ค่าเหล่านี้จะแสดงในหน้าจอความยินยอมที่ Google แสดงต่อผู้ใช้
include_granted_scopes	ไม่บังคับ ค่าเริ่มต้นคือ true ช่วยให้แอปพลิเคชันใช้การให้สิทธิ์แบบเพิ่มทีละส่วนเพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมในบริบทได้ หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และคำขอการให้สิทธิ์ได้รับอนุมัติ โทเค็นการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ขอใน CodeClientConfig นี้
redirect_uri	ต้องระบุสำหรับ UX การเปลี่ยนเส้นทาง กำหนดตำแหน่งที่เซิร์ฟเวอร์ API จะเปลี่ยนเส้นทางผู้ใช้หลังจากที่ผู้ใช้ทำตามขั้นตอนการให้สิทธิ์เสร็จสมบูรณ์ ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสำหรับไคลเอ็นต์ OAuth 2.0 ที่คุณกําหนดค่าไว้ในคอนโซล API และต้องเป็นไปตามกฎการตรวจสอบ URI การเปลี่ยนเส้นทาง UX ของป๊อปอัปจะละเว้นพร็อพเพอร์ตี้นี้
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	ไม่บังคับ โหมด UX ที่จะใช้ในขั้นตอนการให้สิทธิ์ โดยค่าเริ่มต้น ระบบจะเปิดขั้นตอนการขอความยินยอมในป๊อปอัป ค่าที่ใช้ได้คือ popup และ redirect
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	ต้องระบุ รหัสไคลเอ็นต์สําหรับแอปพลิเคชัน คุณดูค่านี้ได้ในคอนโซล API
callback	ต้องระบุ ฟังก์ชัน JavaScript ที่จัดการการตอบกลับโทเค็นที่ส่งคืน
scope	ต้องระบุ รายการขอบเขตที่คั่นด้วยเว้นวรรคซึ่งระบุทรัพยากรที่แอปพลิเคชันของคุณเข้าถึงในนามของผู้ใช้ได้ ค่าเหล่านี้จะแสดงในหน้าจอความยินยอมที่ Google แสดงต่อผู้ใช้
include_granted_scopes	ไม่บังคับ ค่าเริ่มต้นคือ true ช่วยให้แอปพลิเคชันใช้การให้สิทธิ์แบบเพิ่มทีละส่วนเพื่อขอสิทธิ์เข้าถึงขอบเขตเพิ่มเติมในบริบทได้ หากคุณตั้งค่าพารามิเตอร์นี้เป็น false และคำขอการให้สิทธิ์ได้รับอนุมัติ โทเค็นการเข้าถึงใหม่จะครอบคลุมเฉพาะขอบเขตที่ scope ขอใน TokenClientConfig นี้
prompt	ไม่บังคับ ค่าเริ่มต้นคือ 'select_account' รายการพรอมต์ที่คำนึงถึงตัวพิมพ์เล็กและใหญ่และคั่นด้วยเว้นวรรคเพื่อแสดงต่อผู้ใช้ ค่าที่เป็นไปได้มีดังนี้ สตริงว่าง ระบบจะแสดงข้อความแจ้งให้ผู้ใช้ทราบเฉพาะตอนที่แอปขอสิทธิ์เข้าถึงเป็นครั้งแรกเท่านั้น ระบุร่วมกับค่าอื่นๆ ไม่ได้ 'none' ไม่ต้องแสดงหน้าจอการตรวจสอบสิทธิ์หรือความยินยอม ต้องไม่ระบุพร้อมกับค่าอื่นๆ 'consent' แจ้งให้ผู้ใช้ให้ความยินยอม '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[]	ไม่บังคับ ขอบเขตอื่นๆ ที่ควรตรวจสอบ

การคืนสินค้า
บูลีน	เป็นจริงหากมีการให้สิทธิ์เข้าถึงขอบเขตใดขอบเขตหนึ่ง

วิธีการ: 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 มีเฉพาะภาษาอังกฤษเท่านั้น สําหรับข้อผิดพลาดที่พบบ่อยซึ่งแสดงใน error error_description ที่เกี่ยวข้องจะมีลักษณะดังนี้ invalid_token - โทเค็นหมดอายุหรือถูกเพิกถอน invalid_request - เพิกถอนโทเค็นไม่ได้