ใช้โมเดลโค้ด

ไลบรารี Google Identity Services ช่วยให้ผู้ใช้ขอรหัสการให้สิทธิ์จาก Google ได้โดยใช้โฟลว์ UX แบบป๊อปอัปหรือการเปลี่ยนเส้นทางที่อิงตามเบราว์เซอร์ ซึ่งจะเริ่มขั้นตอน OAuth 2.0 ที่ปลอดภัยและส่งผลให้ได้โทเค็นเพื่อการเข้าถึงที่ใช้ในการเรียก Google APIs ในนามของผู้ใช้

สรุปขั้นตอนรหัสการให้สิทธิ์ OAuth 2.0

• จากเบราว์เซอร์ โดยใช้ท่าทางสัมผัส เช่น การคลิกปุ่ม เจ้าของบัญชี Google จะขอรหัสการให้สิทธิ์จาก Google
• Google จะตอบกลับโดยส่งรหัสการให้สิทธิ์ที่ไม่ซ้ำกันไปยังการเรียกกลับใน เว็บแอป JavaScript ที่ทำงานในเบราว์เซอร์ของผู้ใช้ หรือเรียกใช้ ปลายทางรหัสการให้สิทธิ์โดยตรงโดยใช้การเปลี่ยนเส้นทางของเบราว์เซอร์
• แพลตฟอร์มแบ็กเอนด์ของคุณจะโฮสต์ปลายทางรหัสการให้สิทธิ์และรับ รหัส หลังจากตรวจสอบแล้ว แพลตฟอร์มจะแลกเปลี่ยนรหัสนี้ต่อผู้ใช้เพื่อรับโทเค็นการเข้าถึงและโทเค็นการรีเฟรชโดยใช้คำขอไปยังปลายทางโทเค็นของ Google
• Google จะตรวจสอบรหัสการให้สิทธิ์ ยืนยันว่าคำขอมาจากแพลตฟอร์มที่ปลอดภัยของคุณ ออกโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช แล้วส่งคืนโทเค็นโดยเรียกใช้ปลายทางการเข้าสู่ระบบที่แพลตฟอร์มของคุณโฮสต์
• ปลายทางการเข้าสู่ระบบจะได้รับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช โดยจะจัดเก็บโทเค็นการรีเฟรชอย่างปลอดภัยเพื่อใช้ในภายหลัง

ประเด็นสำคัญ: ในเซิร์ฟเวอร์แบ็กเอนด์ คุณจะแลกรหัสการให้สิทธิ์เป็น โทเค็นการรีเฟรชและโทเค็นเพื่อการเข้าถึงได้โดยเรียกใช้ปลายทางโทเค็นของ Google

ข้อกำหนดเบื้องต้น

ทำตามขั้นตอนที่อธิบายไว้ในการตั้งค่าเพื่อกำหนดค่าหน้าจอขอความยินยอม OAuth รับรหัสไคลเอ็นต์ และโหลดไลบรารีของไคลเอ็นต์

เริ่มต้นไคลเอ็นต์โค้ด

เมธอด google.accounts.oauth2.initCodeClient() จะเริ่มต้นไคลเอ็นต์โค้ด

โหมดป๊อปอัปหรือเปลี่ยนเส้นทาง

คุณเลือกแชร์รหัสการให้สิทธิ์โดยใช้โฟลว์ผู้ใช้ในโหมดเปลี่ยนเส้นทางหรือ ป๊อปอัปก็ได้ ในโหมดเปลี่ยนเส้นทาง คุณจะโฮสต์ปลายทางการให้สิทธิ์ OAuth2 ในเซิร์ฟเวอร์ และ Google จะเปลี่ยนเส้นทาง User-Agent ไปยังปลายทางนี้ โดยแชร์รหัสการให้สิทธิ์เป็นพารามิเตอร์ URL สำหรับโหมดป๊อปอัป คุณจะกำหนดตัวแฮนเดิลการเรียกกลับของ JavaScript ซึ่งจะส่งรหัสการให้สิทธิ์ไปยังเซิร์ฟเวอร์ คุณสามารถ ใช้โหมดป๊อปอัปเพื่อมอบประสบการณ์การใช้งานที่ราบรื่นโดยไม่ต้องให้ผู้เข้าชม ออกจากเว็บไซต์

วิธีเริ่มต้นใช้งานไคลเอ็นต์สำหรับ

• เปลี่ยนเส้นทางการไหลของ UX ตั้งค่า ux_mode เป็น redirect และค่าของ redirect_uri ไปยังปลายทางการให้รหัสการให้สิทธิ์ของแพลตฟอร์ม ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตอย่างใดอย่างหนึ่งสำหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกำหนดค่าไว้ใน Google Cloud Console นอกจากนี้ยังต้องเป็นไปตามกฎการตรวจสอบ URI การเปลี่ยนเส้นทางด้วย

• โฟลว์ UX ของป๊อปอัป ให้ตั้งค่า ux_mode เป็น popup และค่าของ callback เป็นชื่อฟังก์ชันที่คุณจะใช้เพื่อส่งรหัสการให้สิทธิ์ไปยังแพลตฟอร์มของคุณ ค่าของ redirect_uri จะเป็นค่าเริ่มต้นของต้นทางของหน้าที่เรียก initCodeClient ขั้นตอนการทำงานจะใช้ค่านี้ในภายหลังเมื่อคุณ แลกรหัสการให้สิทธิ์เป็นโทเค็นเพื่อการเข้าถึงหรือโทเค็นการรีเฟรช เช่น https://www.example.com/index.html เรียก initCodeClient และต้นทาง https://www.example.com คือค่าของ redirect_url

ประเด็นสำคัญ: เราขอแนะนำให้ใช้ UX โหมดป๊อปอัปที่มีรูปแบบรหัสการให้สิทธิ์เพื่อให้ความสมดุลที่ดีที่สุดระหว่างความสามารถในการใช้งานและความปลอดภัย

ป้องกันการโจมตี CSRF

โฟลว์ UX ของโหมดเปลี่ยนเส้นทางและป๊อปอัปใช้เทคนิคที่แตกต่างกันเล็กน้อยเพื่อช่วย ป้องกันการโจมตีแบบ Cross-Site-Request-Forgery (CSRF) สำหรับโหมดเปลี่ยนเส้นทาง ให้ใช้พารามิเตอร์ state ของ OAuth 2.0 ดูข้อมูลเพิ่มเติมเกี่ยวกับการสร้างและตรวจสอบพารามิเตอร์ state ได้ที่ส่วนที่ 10.12 ของ RFC6749 การปลอมแปลงคำขอข้ามเว็บไซต์ ในโหมดป๊อปอัป คุณจะเพิ่มส่วนหัว HTTP ที่กำหนดเองลงในคำขอ จากนั้นในเซิร์ฟเวอร์ ให้ยืนยัน ว่าตรงกับค่าและต้นทางที่คาดไว้

เลือกโหมด UX เพื่อดูข้อมูลโค้ดที่แสดงรหัสการให้สิทธิ์และการจัดการ CSRF

โหมดเปลี่ยนเส้นทาง

เริ่มต้นไคลเอ็นต์ที่ Google เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยัง ปลายทางการตรวจสอบสิทธิ์ของคุณ โดยแชร์รหัสการให้สิทธิ์เป็นพารามิเตอร์ URL

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'redirect',
  redirect_uri: 'https://oauth2.example.com/code',
  state: 'YOUR_BINDING_VALUE'
});

ประเด็นสำคัญ: ปลายทางในเซิร์ฟเวอร์แบ็กเอนด์รับและตรวจสอบ รหัสการให้สิทธิ์ แลกเปลี่ยนเป็นโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช

โหมดป๊อปอัป

เริ่มต้นไคลเอ็นต์ที่ผู้ใช้เริ่มขั้นตอนการให้สิทธิ์ในกล่องโต้ตอบป๊อปอัป หลังจากได้รับความยินยอมแล้ว Google จะส่งรหัสการให้สิทธิ์ ไปยังเบราว์เซอร์ของผู้ใช้โดยใช้ฟังก์ชันเรียกกลับ คำขอ POST จากตัวแฮนเดิลการเรียกกลับของ JS จะส่งรหัสการให้สิทธิ์ไปยังปลายทางในเซิร์ฟเวอร์แบ็กเอนด์ ซึ่งคุณจะยืนยันรหัสดังกล่าวก่อน จากนั้นจึงทำขั้นตอนที่เหลือของโฟลว์ OAuth ให้เสร็จสมบูรณ์

const client = google.accounts.oauth2.initCodeClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  ux_mode: 'popup',
  callback: (response) => {
    const xhr = new XMLHttpRequest();
    xhr.open('POST', "https://oauth2.example.com/code", true);
    xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    // Set custom header for CRSF
    xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
    xhr.onload = function() {
      console.log('Auth code response: ' + xhr.responseText);
    };
    xhr.send('code=' + response.code);
  },
});

ประเด็นสำคัญ: ปลายทางในเซิร์ฟเวอร์แบ็กเอนด์รับและตรวจสอบ รหัสการให้สิทธิ์ แลกเปลี่ยนเป็นโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช

ทริกเกอร์โฟลว์ของรหัส OAuth 2.0

เรียกใช้เมธอด requestCode() ของไคลเอ็นต์โค้ดเพื่อทริกเกอร์โฟลว์ผู้ใช้

<button onclick="client.requestCode();">Authorize with Google</button>

ซึ่งจะกำหนดให้ผู้ใช้ลงชื่อเข้าใช้บัญชี Google และยินยอมที่จะแชร์ ขอบเขตแต่ละรายการก่อนที่จะส่งคืนรหัสการให้สิทธิ์ไปยัง ปลายทางการเปลี่ยนเส้นทางหรือตัวแฮนเดิลการเรียกกลับ

การจัดการรหัสการตรวจสอบสิทธิ์

Google จะสร้างรหัสการให้สิทธิ์ที่ไม่ซ้ำกันต่อผู้ใช้ ซึ่งคุณจะได้รับและ ยืนยันในเซิร์ฟเวอร์แบ็กเอนด์

สำหรับโหมดป๊อปอัป ตัวแฮนเดิลที่ระบุโดย callback ซึ่งทำงานในเบราว์เซอร์ของผู้ใช้จะส่งต่อรหัสการให้สิทธิ์ไปยังปลายทางที่แพลตฟอร์มของคุณโฮสต์

สำหรับโหมดเปลี่ยนเส้นทาง Google จะส่งGETคำขอไปยังปลายทางที่ระบุโดย redirect_uri โดยแชร์รหัสการให้สิทธิ์ในพารามิเตอร์ code ของ URL วิธี รับรหัสการให้สิทธิ์

• สร้างปลายทางการให้สิทธิ์ใหม่ หากคุณไม่มีการติดตั้งใช้งานที่มีอยู่ หรือ

• อัปเดตปลายทางที่มีอยู่ให้ยอมรับคำขอ GET และพารามิเตอร์ URL ก่อนหน้านี้ Google จะส่งPUTคำขอที่มีค่ารหัสการให้สิทธิ์ ในเพย์โหลด

ปลายทางการให้สิทธิ์

ปลายทางรหัสการให้สิทธิ์ต้องจัดการคำขอ GET ที่มีพารามิเตอร์สตริงการค้นหา URL ต่อไปนี้

ชื่อ	ค่า
authuser	คำขอการตรวจสอบสิทธิ์การลงชื่อเข้าใช้ของผู้ใช้
รหัส	รหัสการให้สิทธิ์ OAuth2 ที่ Google สร้างขึ้น
HD	โดเมนที่โฮสต์ของบัญชีผู้ใช้
prompt	กล่องโต้ตอบความยินยอมของผู้ใช้
ขอบเขต	รายการขอบเขต OAuth2 อย่างน้อย 1 รายการที่คั่นด้วยช่องว่างซึ่งจะได้รับอนุญาต
รัฐ	ตัวแปรสถานะ CRSF

ตาม RFC 6749 ไคลเอ็นต์ต้องไม่สนใจพารามิเตอร์การตอบกลับที่ไม่รู้จัก ไม่ว่าพารามิเตอร์เหล่านั้นจะอยู่ในตารางก่อนหน้าหรือไม่ก็ตาม

ตัวอย่างคำขอ GET ที่มีพารามิเตอร์ของ URL ไปยังปลายทางชื่อ auth-code และ โฮสต์โดย example.com

Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent

เมื่อคุณเริ่มขั้นตอนรหัสการให้สิทธิ์โดยใช้ไลบรารี JavaScript เวอร์ชันก่อนหน้า หรือโดยการเรียกปลายทาง Google OAuth 2.0 โดยตรง Google จะส่งคำขอ POST

ตัวอย่างคำขอ POST ที่มีรหัสการให้สิทธิ์เป็นเพย์โหลดในเนื้อหาคำขอ HTTP

Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw

สำคัญ: ก่อนหน้านี้มีการใช้ POST สำหรับคำขอ อัปเดตแฮนเดิลเลอร์ให้ยอมรับทั้งคำขอ GET และ POST หรือพิจารณาโฮสต์ปลายทาง 2 รายการที่แตกต่างกันหากคุณวางแผนที่จะใช้ไลบรารี JS เวอร์ชันเก่าต่อไปหรือเรียกใช้ปลายทาง Google OAuth 2.0 โดยตรงขณะใช้ไลบรารีบริการระบุตัวตนของ Google

ตรวจสอบคำขอ

ในเซิร์ฟเวอร์ ให้ทำดังนี้เพื่อช่วยหลีกเลี่ยงการโจมตีแบบ CSRF

ตรวจสอบค่าของพารามิเตอร์ state สำหรับโหมดเปลี่ยนเส้นทาง

ยืนยันว่ามีส่วนหัว X-Requested-With: XmlHttpRequest สำหรับ โหมดป๊อปอัป

จากนั้นคุณควรดำเนินการขอโทเค็นการรีเฟรชและโทเค็นเพื่อการเข้าถึงจาก Google ก็ต่อเมื่อคุณยืนยันคำขอรหัสการให้สิทธิ์สำเร็จแล้วเท่านั้น

รับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช

หลังจากแพลตฟอร์มแบ็กเอนด์ได้รับรหัสการให้สิทธิ์จาก Google และ ยืนยันคำขอแล้ว ให้ใช้รหัสการให้สิทธิ์เพื่อรับโทเค็นการเข้าถึงและโทเค็นการรีเฟรชจาก Google เพื่อทำการเรียก API

ทำตามวิธีการโดยเริ่มที่ขั้นตอนที่ 5: แลกเปลี่ยนรหัสการให้สิทธิ์เป็นโทเค็นรีเฟรชและโทเค็นการเข้าถึงในคู่มือการใช้ OAuth 2.0 สำหรับแอปพลิเคชันเว็บเซิร์ฟเวอร์

หมายเหตุ: เมื่อใช้โหมดป๊อปอัป ค่า redirect_uri ที่คุณใช้ในขั้นตอนที่ 5 และ หลังจากนั้นคือต้นทางของหน้าเว็บที่เรียก เช่น https://www.example.com/index.html การโทร initCodeClient และต้นทาง https://www.example.com คือค่าของ redirect_url

จัดการโทเค็น

แพลตฟอร์มของคุณจะจัดเก็บโทเค็นการรีเฟรชอย่างปลอดภัย ลบโทเค็นการรีเฟรชที่จัดเก็บไว้เมื่อ คุณนำบัญชีผู้ใช้ออก หรือผู้ใช้เพิกถอนความยินยอมโดย google.accounts.oauth2.revoke หรือโดยตรงจาก https://myaccount.google.com/permissions

คุณอาจพิจารณาใช้ RISC เพื่อปกป้องบัญชีผู้ใช้ด้วยการป้องกันข้ามบัญชีก็ได้

โดยปกติแล้ว แพลตฟอร์มแบ็กเอนด์จะเรียกใช้ Google APIs โดยใช้โทเค็นการเข้าถึง หากเว็บแอปของคุณจะเรียกใช้ Google APIs จากเบราว์เซอร์ของผู้ใช้โดยตรง คุณต้องใช้วิธีแชร์โทเค็นการเข้าถึงกับเว็บแอปพลิเคชันของคุณ ซึ่งอยู่นอกขอบเขตของคู่มือนี้ เมื่อทำตามแนวทางนี้และใช้ไลบรารีของไคลเอ็นต์ Google API สำหรับ JavaScript ให้ใช้ gapi.client.SetToken() เพื่อจัดเก็บโทเค็นการเข้าถึงไว้ในหน่วยความจำของเบราว์เซอร์ชั่วคราว และเปิดใช้ไลบรารีเพื่อเรียกใช้ Google API