Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

OpenID Connect

API ของ OAuth 2.0 ของ Google ใช้ได้ทั้งสำหรับการตรวจสอบสิทธิ์และการให้สิทธิ์ เอกสารนี้อธิบายการติดตั้งใช้งาน OAuth 2.0 สำหรับการตรวจสอบสิทธิ์ ซึ่งเป็นไปตามข้อกำหนด OpenID Connect และได้รับการรับรอง OpenID เอกสารประกอบที่อยู่ในการใช้ OAuth 2.0 เพื่อเข้าถึง Google APIs ยังใช้กับบริการนี้ด้วย หากต้องการสำรวจโปรโตคอลนี้แบบอินเทอร์แอกทีฟ เราขอแนะนำให้ใช้ Google OAuth 2.0 Playground หากต้องการความช่วยเหลือใน Stack Overflow ให้ติดแท็กคำถามด้วย "google-oauth"

การตั้งค่า OAuth 2.0

ก่อนที่แอปพลิเคชันจะใช้ระบบการตรวจสอบสิทธิ์ OAuth 2.0 ของ Google สำหรับการเข้าสู่ระบบของผู้ใช้ได้ คุณต้องตั้งค่าโปรเจ็กต์ในคอนโซล Google Cloud เพื่อรับข้อมูลเข้าสู่ระบบ OAuth 2.0, ตั้งค่า URI เปลี่ยนเส้นทาง และ (ไม่บังคับ) ปรับแต่งข้อมูลการสร้างแบรนด์ที่ผู้ใช้เห็นในหน้าจอขอความยินยอมของผู้ใช้ นอกจากนี้ คุณยังใช้ Cloud Console เพื่อสร้างบัญชีบริการ เปิดใช้การเรียกเก็บเงิน ตั้งค่าการกรอง และทำงานอื่นๆ ได้ด้วย ดูรายละเอียดเพิ่มเติมได้ที่ความช่วยเหลือของคอนโซล Google Cloud

รับข้อมูลเข้าสู่ระบบ OAuth 2.0

คุณต้องมีข้อมูลเข้าสู่ระบบ OAuth 2.0 ซึ่งรวมถึงรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์ เพื่อตรวจสอบสิทธิ์ผู้ใช้และรับสิทธิ์เข้าถึง API ของ Google

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

หรือดูรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์จากหน้าไคลเอ็นต์ใน Cloud Console โดยทำดังนี้

ไปที่หน้าลูกค้า
คลิกชื่อลูกค้าหรือไอคอนแก้ไข () รหัสไคลเอ็นต์และรหัสลับจะอยู่ที่ด้านบนของหน้า

ตั้งค่า URI การเปลี่ยนเส้นทาง

URI การเปลี่ยนเส้นทางที่คุณตั้งค่าใน Cloud Console จะกำหนดตำแหน่งที่ Google ส่งการตอบกลับไปยังคำขอการตรวจสอบสิทธิ์ของคุณ

หากต้องการสร้าง ดู หรือแก้ไข URI เปลี่ยนเส้นทางสำหรับข้อมูลเข้าสู่ระบบ OAuth 2.0 ที่ระบุ ให้ทำดังนี้

ไปที่หน้าลูกค้า
คลิกที่ลูกค้า
ดูหรือแก้ไข URI การเปลี่ยนเส้นทาง

หากไม่มีไคลเอ็นต์ที่แสดงในหน้าไคลเอ็นต์ แสดงว่าโปรเจ็กต์ของคุณไม่มีข้อมูลเข้าสู่ระบบ OAuth หากต้องการสร้าง ให้คลิกสร้างลูกค้า

ปรับแต่งหน้าจอขอความยินยอมจากผู้ใช้

สำหรับผู้ใช้ ประสบการณ์การตรวจสอบสิทธิ์ OAuth 2.0 จะมีหน้าจอขอความยินยอมที่อธิบายข้อมูลที่ผู้ใช้กำลังเผยแพร่และข้อกำหนดที่เกี่ยวข้อง ตัวอย่างเช่น เมื่อผู้ใช้เข้าสู่ระบบ ระบบอาจขอให้ผู้ใช้ให้สิทธิ์แอปของคุณเข้าถึงอีเมลและข้อมูลบัญชีพื้นฐาน คุณขอสิทธิ์เข้าถึงข้อมูลนี้โดยใช้พารามิเตอร์ scope ซึ่งแอปรวมไว้ในคำขอตรวจสอบสิทธิ์ นอกจากนี้ คุณยังใช้ขอบเขตเพื่อขอสิทธิ์เข้าถึง Google APIs อื่นๆ ได้ด้วย

หน้าจอขอความยินยอมจากผู้ใช้ยังแสดงข้อมูลการสร้างแบรนด์ เช่น ชื่อผลิตภัณฑ์ โลโก้ และ URL ของหน้าแรกด้วย คุณควบคุมข้อมูลการสร้างแบรนด์ได้ใน Cloud Console

วิธีเปิดใช้หน้าจอขอความยินยอมของโปรเจ็กต์

เปิดหน้าการสร้างแบรนด์ในคอนโซล Google Cloud
หากได้รับข้อความแจ้ง ให้เลือกโปรเจ็กต์หรือสร้างโปรเจ็กต์ใหม่
กรอกแบบฟอร์มแล้วคลิกบันทึก

กล่องโต้ตอบความยินยอมต่อไปนี้แสดงสิ่งที่ผู้ใช้จะเห็นเมื่อมีทั้งขอบเขต OAuth 2.0 และ Google ไดรฟ์อยู่ในคำขอ (กล่องโต้ตอบทั่วไปนี้สร้างขึ้นโดยใช้ Google OAuth 2.0 Playground จึงไม่มีข้อมูลการสร้างแบรนด์ที่จะตั้งค่าใน Cloud Console)

ตัวอย่างหน้าความยินยอม — **รูปที่ 1** ภาพหน้าจอของหน้าขอความยินยอม

การเข้าถึงบริการ

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

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

หากเลือกที่จะไม่ใช้ไลบรารี ให้ทำตามวิธีการในส่วนที่เหลือของเอกสารนี้ ซึ่งอธิบายขั้นตอนคำขอ HTTP ที่เป็นพื้นฐานของไลบรารีที่พร้อมใช้งาน

การตรวจสอบสิทธิ์ผู้ใช้

การตรวจสอบสิทธิ์ผู้ใช้เกี่ยวข้องกับการรับโทเค็นระบุตัวตนและการตรวจสอบความถูกต้องของโทเค็น โทเค็นระบุตัวตนเป็นฟีเจอร์มาตรฐานของ OpenID Connect ที่ออกแบบมาเพื่อใช้ในการแชร์การยืนยันตัวตนบนอินเทอร์เน็ต

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

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

โฟลว์เซิร์ฟเวอร์

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

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

1. สร้างโทเค็นสถานะป้องกันการปลอมแปลง

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

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

โค้ดต่อไปนี้แสดงการสร้างโทเค็นของเซสชันที่ไม่ซ้ำกัน

PHP

คุณต้องดาวน์โหลดไลบรารีของไคลเอ็นต์ Google APIs สำหรับ PHP เพื่อใช้ตัวอย่างนี้

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

คุณต้องดาวน์โหลดไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java เพื่อใช้ตัวอย่างนี้

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

คุณต้องดาวน์โหลดไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Python เพื่อใช้ตัวอย่างนี้

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. ส่งคำขอการตรวจสอบสิทธิ์ไปยัง Google

ขั้นตอนถัดไปคือการสร้างคำขอ HTTPS GET ด้วยพารามิเตอร์ URI ที่เหมาะสม โปรดทราบว่าต้องใช้ HTTPS แทน HTTP ในทุกขั้นตอนของกระบวนการนี้ ระบบจะปฏิเสธการเชื่อมต่อ HTTP คุณควรดึงข้อมูล URI พื้นฐานจากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา authorization_endpoint การสนทนาต่อไปนี้จะถือว่า URI พื้นฐานคือ https://accounts.google.com/o/oauth2/v2/auth

สำหรับคำขอพื้นฐาน ให้ระบุพารามิเตอร์ต่อไปนี้

client_id ซึ่งคุณจะได้รับจากหน้าไคลเอ็นต์ของ Cloud Console
response_type ซึ่งในคำขอขั้นตอนรหัสการให้สิทธิ์พื้นฐานควรเป็น code (อ่านเพิ่มเติมได้ที่ response_type)
scope ซึ่งในคำขอพื้นฐานควรเป็น openid email (อ่านเพิ่มเติมที่ scope)
redirect_uri ควรเป็นปลายทาง HTTP บนเซิร์ฟเวอร์ของคุณที่จะได้รับการตอบกลับจาก Google ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตรายการใดรายการหนึ่งสำหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกำหนดค่าไว้ในหน้าข้อมูลเข้าสู่ระบบของ Cloud Console หากค่านี้ไม่ตรงกับ URI ที่ได้รับอนุญาต คำขอจะดำเนินการไม่สำเร็จและแสดงข้อผิดพลาด redirect_uri_mismatch
state ควรมีค่าของโทเค็นของเซสชันที่ไม่ซ้ำกันเพื่อป้องกันการปลอมแปลง รวมถึงข้อมูลอื่นๆ ที่จำเป็นในการกู้คืนบริบทเมื่อผู้ใช้กลับมาที่แอปพลิเคชันของคุณ เช่น URL เริ่มต้น (อ่านเพิ่มเติมที่ state)
nonce คือค่าแบบสุ่มที่แอปสร้างขึ้นซึ่งจะเปิดใช้การป้องกันการเล่นซ้ำเมื่อมีค่านี้
login_hint อาจเป็นอีเมลของผู้ใช้หรือสตริง sub ซึ่งเทียบเท่ากับรหัส Google ของผู้ใช้ หากคุณไม่ระบุ login_hint และผู้ใช้เข้าสู่ระบบ หน้าจอขอความยินยอมจะมีคำขออนุมัติเพื่อเปิดเผยอีเมลของผู้ใช้ให้แอปของคุณทราบ (อ่านเพิ่มเติมได้ที่ login_hint)
ใช้พารามิเตอร์ hd เพื่อเพิ่มประสิทธิภาพขั้นตอน OpenID Connect สำหรับผู้ใช้ของโดเมนหนึ่งๆ ที่เชื่อมโยงกับองค์กร Google Workspace หรือ Cloud (อ่านข้อมูลเพิ่มเติมได้ที่ hd)

ต่อไปนี้คือตัวอย่าง URI การตรวจสอบสิทธิ์ OpenID Connect ที่สมบูรณ์ โดยมีการขึ้นบรรทัดใหม่และเว้นวรรคเพื่อให้อ่านง่าย

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//developers.google.com/oauthplayground&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

ผู้ใช้ต้องให้ความยินยอมหากแอปของคุณขอข้อมูลใหม่เกี่ยวกับผู้ใช้ หรือหากแอปของคุณขอสิทธิ์เข้าถึงบัญชีที่ผู้ใช้ไม่เคยอนุมัติมาก่อน

3. ยืนยันโทเค็นสถานะการป้องกันการปลอมแปลง

ระบบจะส่งคำตอบไปยัง redirect_uri ที่คุณระบุไว้ในคำขอ ระบบจะแสดงคำตอบทั้งหมดในสตริงการค้นหา ดังนี้

https://developers.google.com/oauthplayground?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

ตาม RFC 6749 ไคลเอ็นต์ต้องไม่สนใจพารามิเตอร์การตอบกลับที่ไม่รู้จัก ในเซิร์ฟเวอร์ คุณต้องยืนยันว่า state ที่ได้รับจาก Google ตรงกับโทเค็นของเซสชันที่คุณสร้างในขั้นตอนที่ 1 การยืนยันแบบไปกลับนี้ช่วยยืนยันว่าผู้ใช้เป็นผู้ส่งคำขอ ไม่ใช่สคริปต์ที่เป็นอันตราย

โค้ดต่อไปนี้แสดงการยืนยันโทเค็นของเซสชันที่คุณสร้างในขั้นตอนที่ 1

PHP

คุณต้องดาวน์โหลดไลบรารีของไคลเอ็นต์ Google APIs สำหรับ PHP เพื่อใช้ตัวอย่างนี้

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

คุณต้องดาวน์โหลดไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java เพื่อใช้ตัวอย่างนี้

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. แลกเปลี่ยน `code` เป็นโทเค็นเพื่อการเข้าถึงและโทเค็นระบุตัวตน

การตอบกลับจะมีพารามิเตอร์ code ซึ่งเป็นรหัสการให้สิทธิ์แบบครั้งเดียวที่เซิร์ฟเวอร์สามารถแลกเปลี่ยนเป็นโทเค็นเพื่อการเข้าถึงและโทเค็นระบุตัวตนได้ เซิร์ฟเวอร์ของคุณจะทำการแลกเปลี่ยนนี้โดยส่งคำขอ HTTPS POST ระบบจะส่งคำขอ POST ไปยังปลายทางโทเค็น ซึ่งคุณควรดึงข้อมูลจากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา token_endpoint การสนทนาต่อไปนี้จะถือว่าปลายทางคือ https://oauth2.googleapis.com/token คำขอต้องมีพารามิเตอร์ต่อไปนี้ในเนื้อหา POST

ช่อง
`code`	รหัสการให้สิทธิ์ที่ส่งกลับมาจากคำขอเริ่มต้น
`client_id`	รหัสไคลเอ็นต์ที่คุณได้รับจากหน้าไคลเอ็นต์ของ Cloud Console ตามที่อธิบายไว้ในรับข้อมูลเข้าสู่ระบบ OAuth 2.0
`client_secret`	รหัสลับไคลเอ็นต์ที่คุณได้รับจากหน้าไคลเอ็นต์ของ Cloud Console ตามที่อธิบายไว้ในรับข้อมูลเข้าสู่ระบบ OAuth 2.0
`redirect_uri`	URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสำหรับ `client_id` ที่ระบุในหน้าไคลเอ็นต์ของ Cloud Console ตามที่อธิบายไว้ในตั้งค่า URI การเปลี่ยนเส้นทาง
`grant_type`	ช่องนี้ต้องมีค่าเป็น `authorization_code` ตามที่กำหนดไว้ในข้อกำหนดเฉพาะของ OAuth 2.0

คำขอจริงอาจมีลักษณะดังตัวอย่างต่อไปนี้

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//developers.google.com/oauthplayground&
grant_type=authorization_code

การตอบกลับคำขอนี้ที่สำเร็จจะมีช่องต่อไปนี้ในอาร์เรย์ JSON

ช่อง
`access_token`	โทเค็นที่ส่งไปยัง Google API ได้
`expires_in`	อายุการใช้งานที่เหลือของโทเค็นเพื่อการเข้าถึงเป็นวินาที
`id_token`	JWT ที่มีข้อมูลประจำตัวเกี่ยวกับผู้ใช้ที่ Google ลงนามแบบดิจิทัล
`scope`	ขอบเขตของสิทธิ์เข้าถึงที่ `access_token` มอบให้จะแสดงเป็นรายการสตริงที่คั่นด้วยช่องว่างและคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
`token_type`	ระบุประเภทของโทเค็นที่แสดงผล ในขณะนี้ ช่องนี้จะมีค่าเป็น `Bearer` เสมอ
`refresh_token`	(ไม่บังคับ) ช่องนี้จะปรากฏก็ต่อเมื่อมีการตั้งค่าพารามิเตอร์ `access_type` เป็น `offline` ในคำขอตรวจสอบสิทธิ์ โปรดดูรายละเอียดที่หัวข้อโทเค็นการรีเฟรช

5. รับข้อมูลผู้ใช้จากโทเค็นระบุตัวตน

โทเค็นระบุตัวตนคือ JWT (JSON Web Token) ซึ่งเป็นออบเจ็กต์ JSON ที่เข้ารหัส Base64 และลงนามด้วยการเข้ารหัส โดยปกติแล้ว คุณจำเป็นต้องตรวจสอบความถูกต้องของโทเค็นระบุตัวตนก่อนใช้งาน แต่เนื่องจากคุณสื่อสารกับ Google โดยตรงผ่านช่องทาง HTTPS ที่ไม่มีสื่อกลางและใช้รหัสลับไคลเอ็นต์เพื่อตรวจสอบสิทธิ์กับ Google คุณจึงมั่นใจได้ว่าโทเค็นที่ได้รับมาจาก Google จริงๆ และถูกต้อง หากเซิร์ฟเวอร์ส่งโทเค็นระบุตัวตนไปยังคอมโพเนนต์อื่นๆ ของแอป คุณจำเป็นอย่างยิ่งที่จะต้องให้คอมโพเนนต์อื่นๆ ตรวจสอบโทเค็นก่อนใช้งาน

เนื่องจากไลบรารี API ส่วนใหญ่จะรวมการตรวจสอบเข้ากับการถอดรหัสค่าที่เข้ารหัส base64url และแยกวิเคราะห์ JSON ภายใน คุณจึงอาจต้องตรวจสอบโทเค็นอยู่ดีเมื่อเข้าถึงการอ้างสิทธิ์ในโทเค็นระบุตัวตน

เพย์โหลดของโทเค็นระบุตัวตน

โทเค็นระบุตัวตนคือออบเจ็กต์ JSON ที่มีชุดคู่ชื่อ/ค่า ตัวอย่างที่จัดรูปแบบให้อ่านง่ายมีดังนี้

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

โทเค็นรหัสของ Google อาจมีช่องต่อไปนี้ (เรียกว่าการอ้างสิทธิ์)

อ้างสิทธิ์	ระบุแล้ว	คำอธิบาย
`aud`	ทุกครั้ง	กลุ่มเป้าหมายที่โทเค็นระบุตัวตนนี้มีไว้ให้ โดยต้องเป็นรหัสไคลเอ็นต์ OAuth 2.0 ของแอปพลิเคชันของคุณ
`exp`	ทุกครั้ง	เวลาหมดอายุซึ่งต้องไม่ยอมรับโทเค็นระบุตัวตนหลังจากนั้น แสดงในเวลา Unix Epoch (จำนวนเต็มวินาที)
`iat`	ทุกครั้ง	เวลาที่ออกโทเค็นระบุตัวตน แสดงในเวลา Unix Epoch (จำนวนเต็มวินาที)
`iss`	ทุกครั้ง	ตัวระบุผู้ออกสำหรับผู้ออกการตอบกลับ ใช้ `https://accounts.google.com` หรือ `accounts.google.com` สำหรับโทเค็นระบุตัวตนของ Google เสมอ
`sub`	ทุกครั้ง	ตัวระบุสำหรับผู้ใช้ ซึ่งไม่ซ้ำกันในบัญชี Google ทั้งหมดและไม่นำมาใช้ซ้ำ บัญชี Google สามารถมีอีเมลได้หลายอีเมลในแต่ละช่วงเวลา แต่ค่า `sub` จะไม่มีการเปลี่ยนแปลง ใช้ `sub` ภายในแอปพลิเคชันเป็นคีย์ตัวระบุที่ไม่ซ้ำกันสำหรับผู้ใช้ ความยาวสูงสุด 255 อักขระ ASCII ที่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่
`amr`		อาร์เรย์ JSON ของสตริงที่ระบุวิธีการตรวจสอบสิทธิ์ที่ใช้ในการลงชื่อเข้าใช้บัญชี Google หากมี จะรวมค่า [IANA.AMR] ที่เป็นไปได้ต่อไปนี้อย่างน้อย 1 ค่า มีการใช้คีย์ฮาร์ดแวร์ `hwk` ครั้ง `mfa` การตรวจสอบสิทธิ์แบบหลายปัจจัยเสร็จสมบูรณ์แล้ว ใช้รหัสผ่านของ `pwd` ไปแล้ว `sms` มีการใช้ข้อความ SMS เพื่อยืนยัน `swk` มีการใช้คีย์ซอฟต์แวร์ เช่น พาสคีย์ มีการใช้การโทร `tel` ครั้งเพื่อยืนยัน จะแสดงก็ต่อเมื่อมีการรวมการอ้างสิทธิ์ `amr` ไว้ในคำขอการตรวจสอบสิทธิ์และเปิดใช้ในการตั้งค่า
`auth_time`		เวลาที่เกิดการตรวจสอบสิทธิ์ผู้ใช้ ซึ่งเป็นตัวเลข JSON ที่แสดงจำนวนวินาทีที่ผ่านไปนับตั้งแต่ Unix Epoch (1 มกราคม 1970 เวลา 00:00:00 UTC) ระบุเมื่อมีการรวมการอ้างสิทธิ์ `auth_time` ไว้ในคำขอการตรวจสอบสิทธิ์และเปิดใช้ในการตั้งค่า
`at_hash`		แฮชของโทเค็นเพื่อการเข้าถึง ตรวจสอบว่าโทเค็นเพื่อการเข้าถึงเชื่อมโยงกับโทเค็นระบุตัวตน หากมีการออกโทเค็นระบุตัวตนพร้อมค่า `access_token` ในขั้นตอนของเซิร์ฟเวอร์ การอ้างสิทธิ์นี้จะรวมอยู่ด้วยเสมอ การอ้างสิทธิ์นี้สามารถใช้เป็นกลไกทางเลือกเพื่อป้องกันการโจมตีแบบคำขอแบบข้ามเว็บไซต์ แต่หากคุณทำตามขั้นตอนที่ 1 และขั้นตอนที่ 3 ก็ไม่จำเป็นต้องยืนยันโทเค็นเพื่อการเข้าถึง
`azp`		`client_id`ของผู้เสนอที่ได้รับอนุญาต การอ้างสิทธิ์นี้จำเป็นเฉพาะเมื่อฝ่ายที่ขอโทเค็นระบุตัวตนไม่ใช่ฝ่ายเดียวกับกลุ่มเป้าหมายของโทเค็นระบุตัวตน กรณีนี้อาจเกิดขึ้นที่ Google สำหรับแอปแบบไฮบริดที่เว็บแอปพลิเคชันและแอป Android มี `client_id` OAuth 2.0 ที่แตกต่างกัน แต่ใช้โปรเจ็กต์ Google APIs เดียวกัน
`email`		อีเมลของผู้ใช้ ระบุเฉพาะในกรณีที่คุณรวมขอบเขต `email` ไว้ในคำขอ ค่าของการอ้างสิทธิ์นี้อาจไม่ซ้ำกันสำหรับบัญชีนี้และอาจเปลี่ยนแปลงเมื่อเวลาผ่านไป ดังนั้นคุณจึงไม่ควรใช้ค่านี้เป็นตัวระบุหลักเพื่อลิงก์กับบันทึกผู้ใช้ นอกจากนี้ คุณยังไม่สามารถใช้โดเมนของการอ้างสิทธิ์ `email` เพื่อระบุผู้ใช้ขององค์กร Google Workspace หรือ Cloud ได้ แต่ให้ใช้การอ้างสิทธิ์ `hd` แทน คำเตือน: อย่าใช้ช่อง `email` เป็นตัวระบุที่ไม่ซ้ำกันสำหรับผู้ใช้ ใช้ช่อง `sub` เสมอ
`email_verified`		จริง หากอีเมลของผู้ใช้ได้รับการยืนยันแล้ว หรือเป็นเท็จ
`family_name`		นามสกุลของผู้ใช้ อาจระบุเมื่อมีการอ้างสิทธิ์ `name`
`given_name`		ชื่อจริงของผู้ใช้ อาจระบุเมื่อมีการอ้างสิทธิ์ `name`
`hd`		โดเมนที่เชื่อมโยงกับองค์กร Google Workspace หรือ Cloud ของผู้ใช้ ระบุเฉพาะในกรณีที่ผู้ใช้อยู่ในองค์กร Google Cloud คุณต้องตรวจสอบการอ้างสิทธิ์นี้เมื่อจำกัดสิทธิ์เข้าถึงทรัพยากรไว้เฉพาะสมาชิกของบางโดเมนเท่านั้น การไม่มีการอ้างสิทธิ์นี้บ่งชี้ว่าบัญชีไม่ได้เป็นของโดเมนที่ฝากบริการของ Google
`locale`		ภาษาของผู้ใช้ ซึ่งแสดงด้วยแท็กภาษา BCP 47 อาจระบุเมื่อมีการอ้างสิทธิ์ `name`
`name`		ชื่อและนามสกุลของผู้ใช้ในรูปแบบที่แสดงได้ อาจระบุเมื่อ ขอบเขตคำขอมีสตริง "profile" ระบบจะแสดงผลโทเค็นระบุตัวตนจากการรีเฟรชโทเค็น เมื่อมีคำกล่าวอ้าง `name` รายการ คุณสามารถใช้คำกล่าวอ้างเหล่านั้นเพื่ออัปเดตบันทึกผู้ใช้ของแอปได้ โปรดทราบว่าการอ้างสิทธิ์นี้ไม่รับประกันว่าจะแสดงเสมอไป
`nonce`		ค่าของ `nonce` ที่แอปของคุณระบุในคำขอตรวจสอบสิทธิ์ คุณควรป้องกันการโจมตีแบบ Replay Attack โดยแสดงค่านี้เพียงครั้งเดียว
`picture`		URL ของรูปโปรไฟล์ของผู้ใช้ อาจระบุเมื่อ ขอบเขตคำขอมีสตริง "profile" ระบบจะแสดงผลโทเค็นระบุตัวตนจากการรีเฟรชโทเค็น เมื่อมีการอ้างสิทธิ์ `picture` คุณสามารถใช้การอ้างสิทธิ์ดังกล่าวเพื่ออัปเดตบันทึกผู้ใช้ของแอปได้ โปรดทราบว่าการอ้างสิทธิ์นี้ไม่รับประกันว่าจะแสดงเสมอไป
`profile`		URL ของหน้าโปรไฟล์ของผู้ใช้ อาจระบุเมื่อ ขอบเขตคำขอมีสตริง "profile" ระบบจะแสดงผลโทเค็นระบุตัวตนจากการรีเฟรชโทเค็น เมื่อมีการอ้างสิทธิ์ `profile` คุณสามารถใช้การอ้างสิทธิ์ดังกล่าวเพื่ออัปเดตบันทึกผู้ใช้ของแอปได้ โปรดทราบว่าการอ้างสิทธิ์นี้ไม่รับประกันว่าจะแสดงเสมอไป

6. ตรวจสอบสิทธิ์ผู้ใช้

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

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

หัวข้อขั้นสูง

ส่วนต่อไปนี้จะอธิบาย Google OAuth 2.0 API โดยละเอียด ข้อมูลนี้มีไว้สำหรับนักพัฒนาแอปที่มีข้อกำหนดขั้นสูงเกี่ยวกับการตรวจสอบสิทธิ์และการให้สิทธิ์

สิทธิ์เข้าถึง Google APIs อื่นๆ

ข้อดีอย่างหนึ่งของการใช้ OAuth 2.0 สำหรับการตรวจสอบสิทธิ์คือแอปพลิเคชันของคุณจะได้รับสิทธิ์ใช้ Google APIs อื่นๆ ในนามของผู้ใช้ (เช่น YouTube, Google ไดรฟ์, ปฏิทิน หรือ Contacts) พร้อมกันกับที่คุณตรวจสอบสิทธิ์ผู้ใช้ โดยให้รวมขอบเขตอื่นๆ ที่คุณต้องการในคำขอการตรวจสอบสิทธิ์ที่ส่งไปยัง Google เช่น หากต้องการเพิ่มกลุ่มอายุของผู้ใช้ในคำขอการตรวจสอบสิทธิ์ ให้ส่งพารามิเตอร์ขอบเขตเป็น openid email https://www.googleapis.com/auth/profile.agerange.read ระบบจะแสดงข้อความแจ้งที่เหมาะสมแก่ผู้ใช้ในหน้าจอขอความยินยอม โทเค็นเพื่อการเข้าถึงที่คุณได้รับกลับมาจาก Google จะช่วยให้แอปพลิเคชันของคุณเข้าถึง API ทั้งหมดที่เกี่ยวข้องกับขอบเขตการเข้าถึงที่คุณขอและได้รับสิทธิ์

โทเค็นการรีเฟรช

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

ข้อควรพิจารณา

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

ดูข้อมูลเพิ่มเติมได้ที่หัวข้อการรีเฟรชโทเค็นเพื่อการเข้าถึง (การเข้าถึงแบบออฟไลน์)

คุณสามารถแจ้งให้ผู้ใช้ให้สิทธิ์แอปของคุณอีกครั้งได้โดยตั้งค่าพารามิเตอร์ prompt เป็น consent ในคำขอการตรวจสอบสิทธิ์ เมื่อรวม prompt=consent ไว้ หน้าจอขอความยินยอมจะแสดงทุกครั้งที่แอปขอสิทธิ์เข้าถึงขอบเขต แม้ว่าก่อนหน้านี้จะมีการให้สิทธิ์ขอบเขตทั้งหมดแก่โปรเจ็กต์ Google APIs แล้วก็ตาม ด้วยเหตุนี้ โปรดใส่ prompt=consent เฉพาะเมื่อจำเป็นเท่านั้น

ดูข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์ prompt ได้ที่ prompt ในตารางพารามิเตอร์ URI การตรวจสอบสิทธิ์

พารามิเตอร์ URI ของการตรวจสอบสิทธิ์

ตารางต่อไปนี้แสดงคำอธิบายที่สมบูรณ์ยิ่งขึ้นเกี่ยวกับพารามิเตอร์ที่ API การตรวจสอบสิทธิ์ OAuth 2.0 ของ Google ยอมรับ

พารามิเตอร์ ต้องระบุ คำอธิบาย

client_id (ต้องระบุ) สตริงรหัสไคลเอ็นต์ที่คุณได้รับจากหน้าไคลเอ็นต์ของ Cloud Console ตามที่อธิบายไว้ในรับข้อมูลเข้าสู่ระบบ OAuth 2.0

nonce (ต้องระบุ) ค่าแบบสุ่มที่แอปสร้างขึ้นซึ่งเปิดใช้การป้องกันการเล่นซ้ำ

response_type (ต้องระบุ) หากค่าเป็น code ระบบจะเปิดขั้นตอนรหัสการให้สิทธิ์พื้นฐาน ซึ่งต้องใช้ POST ไปยังปลายทางโทเค็นเพื่อรับโทเค็น หากค่าเป็น token id_token หรือ id_token token ระบบจะเปิดขั้นตอนการให้สิทธิ์โดยนัย ซึ่งต้องใช้ JavaScript ที่ URI เปลี่ยนเส้นทางเพื่อดึงโทเค็นจากตัวระบุ #fragment ของ URI

redirect_uri (ต้องระบุ) กำหนดตำแหน่งที่จะส่งคำตอบ ค่าของพารามิเตอร์นี้ต้องตรงกับค่าการเปลี่ยนเส้นทางที่ได้รับอนุญาตค่าใดค่าหนึ่งที่คุณตั้งไว้ในหน้าไคลเอ็นต์ของ Cloud Console (รวมถึงรูปแบบ HTTP หรือ HTTPS, ตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ และเครื่องหมาย "/" ต่อท้าย หากมี)

scope

(ต้องระบุ)

พารามิเตอร์ขอบเขตต้องขึ้นต้นด้วยค่า openid แล้วตามด้วยค่า profile, ค่า email หรือทั้ง 2 ค่า

หากมีค่าขอบเขต profile โทเค็นระบุตัวตนอาจ (แต่ไม่รับประกัน) รวมการอ้างสิทธิ์ profile เริ่มต้นของผู้ใช้

หากมีค่าขอบเขต email โทเค็นระบุตัวตนจะมีคำกล่าวอ้าง email และ email_verified

นอกจากขอบเขตเฉพาะ OpenID เหล่านี้แล้ว อาร์กิวเมนต์ขอบเขตยังรวมค่าขอบเขตอื่นๆ ได้ด้วย ค่าขอบเขตทั้งหมดต้องคั่นด้วยเว้นวรรค เช่น หากต้องการสิทธิ์เข้าถึงไฟล์ใน Google ไดรฟ์ของผู้ใช้ พารามิเตอร์ขอบเขตอาจเป็น openid profile email https://www.googleapis.com/auth/drive.file

ดูข้อมูลเกี่ยวกับขอบเขตที่ใช้ได้ที่หัวข้อขอบเขต OAuth 2.0 สำหรับ Google APIs หรือเอกสารประกอบสำหรับ Google API ที่คุณต้องการใช้

state

(ไม่บังคับ แต่แนะนำอย่างยิ่ง)

สตริงทึบแสงที่ส่งไปกลับในโปรโตคอล กล่าวคือ ระบบจะแสดงผลเป็นพารามิเตอร์ URI ในขั้นตอนพื้นฐาน และในตัวระบุ #fragment ของ URI ในขั้นตอนการให้สิทธิ์โดยนัย

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

access_type (ไม่บังคับ) ค่าที่อนุญาตคือ offline และ online ผลลัพธ์จะได้รับการบันทึกไว้ในการเข้าถึงแบบออฟไลน์ หากมีการขอโทเค็นเพื่อการเข้าถึง ไคลเอ็นต์จะไม่ได้รับโทเค็นการรีเฟรช เว้นแต่จะระบุค่า offline ไว้

claims

(ไม่บังคับ)

พารามิเตอร์การอ้างสิทธิ์ใช้เพื่อระบุฟิลด์ที่ไม่บังคับอย่างน้อย 1 ฟิลด์ที่จะรวมไว้ในปลายทาง userinfo หรือประเภทการตอบกลับโทเค็นรหัสคำขอการตรวจสอบสิทธิ์ ค่านี้เป็นออบเจ็กต์ JSON ที่มีประเภทการตอบกลับและการอ้างสิทธิ์ที่ขอ เซิร์ฟเวอร์ของ Google จะยอมรับคำขอการอ้างสิทธิ์ต่อไปนี้

คำขอรับสิทธิ์

amr ขอวิธีการที่ใช้เมื่อผู้ใช้ได้รับการตรวจสอบสิทธิ์ครั้งล่าสุด หากต้องการแสดงผล amr เป็นฟิลด์ในการตอบกลับโทเค็นระบุตัวตน ให้ใส่พารามิเตอร์คำขอ claims ดังนี้ claims={"id_token":{"amr":{"essential":true}}} ต้องเปิดใช้ในการตั้งค่า

auth_time ขอเวลาที่ผู้ใช้ได้รับการตรวจสอบสิทธิ์ครั้งล่าสุด หากต้องการแสดงผล auth_time เป็นฟิลด์ในการตอบกลับโทเค็นระบุตัวตน ให้ใส่พารามิเตอร์คำขอ claims ดังนี้ claims={"id_token":{"auth_time":{"essential":true}}} ต้องเปิดใช้ในการตั้งค่า

display (ไม่บังคับ) ค่าสตริง ASCII สำหรับระบุวิธีที่เซิร์ฟเวอร์การให้สิทธิ์แสดงหน้าอินเทอร์เฟซผู้ใช้สำหรับการตรวจสอบสิทธิ์และความยินยอม ค่าต่อไปนี้ได้รับการระบุและยอมรับโดยเซิร์ฟเวอร์ของ Google แต่ไม่มีผลต่อลักษณะการทำงานของขั้นตอนโปรโตคอล ได้แก่ page, popup, touch และ wap

hd

(ไม่บังคับ)

ปรับปรุงกระบวนการเข้าสู่ระบบสำหรับบัญชีที่องค์กร Google Cloud เป็นเจ้าของ การระบุโดเมนองค์กร Google Cloud (เช่น mycollege.edu) จะช่วยบ่งชี้ว่า UI การเลือกบัญชีควรได้รับการเพิ่มประสิทธิภาพสำหรับบัญชีในโดเมนนั้น หากต้องการเพิ่มประสิทธิภาพให้กับบัญชีองค์กร Google Cloud โดยทั่วไปแทนที่จะเป็นโดเมนองค์กร Google Cloud เพียงโดเมนเดียว ให้ตั้งค่าเป็นเครื่องหมายดอกจัน (*) ดังนี้ hd=*

อย่าพึ่งพาการเพิ่มประสิทธิภาพ UI นี้เพื่อควบคุมผู้ที่เข้าถึงแอปของคุณได้ เนื่องจากคำขอฝั่งไคลเอ็นต์สามารถแก้ไขได้ อย่าลืมตรวจสอบว่าโทเค็นระบุตัวตนที่แสดงผลมีค่าการอ้างสิทธิ์ hd ที่ตรงกับที่คุณคาดไว้ (เช่น mycolledge.edu) การอ้างสิทธิ์ hd ของโทเค็นระบุตัวตนจะอยู่ในโทเค็นความปลอดภัยจาก Google ซึ่งต่างจากพารามิเตอร์คำขอ ดังนั้นค่าจึงเชื่อถือได้

include_granted_scopes

(ไม่บังคับ)

หากระบุพารามิเตอร์นี้ด้วยค่า true และคำขอการให้สิทธิ์ได้รับอนุมัติ การให้สิทธิ์จะรวมการให้สิทธิ์ก่อนหน้านี้ที่มอบให้แก่ชุดค่าผสมของผู้ใช้/แอปพลิเคชันนี้สำหรับขอบเขตอื่นๆ โปรดดู การให้สิทธิ์แบบเพิ่มทีละส่วน

โปรดทราบว่าคุณไม่สามารถทำการให้สิทธิ์แบบเพิ่มขึ้นด้วยขั้นตอนของ Installed App

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

prompt

(ไม่บังคับ)

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

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

หากไม่ได้ระบุค่าไว้และผู้ใช้ไม่เคยให้สิทธิ์เข้าถึงมาก่อน ระบบจะแสดงหน้าจอขอความยินยอมแก่ผู้ใช้

hl (ไม่บังคับ) แท็กภาษา BCP 47 ที่ใช้ระบุภาษาที่แสดงสำหรับหน้าจอลงชื่อเข้าใช้ ตัวเลือกบัญชีผู้ใช้ และหน้าจอขอความยินยอม หากไม่ได้ระบุพารามิเตอร์นี้ ภาษาจะตั้งค่าเริ่มต้นเป็นบัญชี Google หรือการตั้งค่าเบราว์เซอร์ของผู้ใช้ เช่น หากต้องการขอ UI เป็นภาษาอังกฤษแบบบริติช ให้ตั้งค่าพารามิเตอร์เป็น en-GB

การตรวจสอบความถูกต้องของโทเค็นระบุตัวตน

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

ต่อไปนี้คือสถานการณ์ที่พบบ่อยซึ่งคุณอาจส่งโทเค็นระบุตัวตนไปยังเซิร์ฟเวอร์

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

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

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

การตรวจสอบความถูกต้องของโทเค็นระบุตัวตนต้องใช้หลายขั้นตอน ดังนี้

ยืนยันว่าโทเค็นระบุตัวตนได้รับการลงนามอย่างถูกต้องโดยผู้ออก โทเค็นที่ Google ออกให้จะได้รับการรับรองโดยใช้ใบรับรองรายการใดรายการหนึ่งที่พบใน URI ที่ระบุไว้ในค่าข้อมูลเมตา jwks_uri ของเอกสารการค้นพบ
ตรวจสอบว่าค่าของการอ้างสิทธิ์ iss ในโทเค็นระบุตัวตนเท่ากับ https://accounts.google.com หรือ accounts.google.com
ยืนยันว่าค่าของการอ้างสิทธิ์ aud ในโทเค็นระบุตัวตนเท่ากับรหัสไคลเอ็นต์ของแอป
ตรวจสอบว่าเวลาหมดอายุ (การอ้างสิทธิ์ exp) ของโทเค็นระบุตัวตนยังไม่ผ่านไป
หากคุณระบุค่าพารามิเตอร์ hd ในคำขอ ให้ตรวจสอบว่าโทเค็นระบุตัวตนมีการอ้างสิทธิ์ hd ที่ตรงกับโดเมนที่ยอมรับซึ่งเชื่อมโยงกับองค์กร Google Cloud

ขั้นตอนที่ 2 ถึง 5 เกี่ยวข้องกับการเปรียบเทียบสตริงและวันที่เท่านั้น ซึ่งค่อนข้างตรงไปตรงมา เราจึงจะไม่ลงรายละเอียดในที่นี้

ขั้นตอนแรกมีความซับซ้อนมากกว่า และเกี่ยวข้องกับการตรวจสอบลายเซ็นที่เข้ารหัส เพื่อวัตถุประสงค์ในการแก้ไขข้อบกพร่อง คุณสามารถใช้ปลายทาง tokeninfo ของ Google เพื่อเปรียบเทียบกับการประมวลผลในเครื่องที่ติดตั้งใช้งานในเซิร์ฟเวอร์หรืออุปกรณ์ของคุณ สมมติว่าค่าของโทเค็นระบุตัวตนคือ XYZ123 จากนั้นคุณจะยกเลิกการอ้างอิง URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123 หากลายเซ็นโทเค็นถูกต้อง การตอบกลับจะเป็นเพย์โหลด JWT ในรูปแบบออบเจ็กต์ JSON ที่ถอดรหัสแล้ว

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

เนื่องจาก Google เปลี่ยนคีย์สาธารณะไม่บ่อยนัก คุณจึงแคชคีย์สาธารณะได้โดยใช้คำสั่งแคชของการตอบกลับ HTTP และในกรณีส่วนใหญ่ คุณจะทำการตรวจสอบในเครื่องได้อย่างมีประสิทธิภาพมากกว่าการใช้ปลายทาง tokeninfo การตรวจสอบนี้ต้องมีการดึงข้อมูลและแยกวิเคราะห์ใบรับรอง รวมถึงทำการเรียกใช้การเข้ารหัสที่เหมาะสมเพื่อตรวจสอบลายเซ็น โชคดีที่มีไลบรารีที่แก้ไขข้อบกพร่องแล้วในภาษาต่างๆ มากมายเพื่อดำเนินการนี้ให้สำเร็จ (ดู jwt.io)

การรับข้อมูลโปรไฟล์ผู้ใช้

หากต้องการดูข้อมูลโปรไฟล์เพิ่มเติมเกี่ยวกับผู้ใช้ คุณสามารถใช้โทเค็นเพื่อการเข้าถึง (ซึ่งแอปพลิเคชันของคุณได้รับระหว่างขั้นตอนการตรวจสอบสิทธิ์) และมาตรฐาน OpenID Connect ได้ ดังนี้

หากต้องการให้เป็นไปตามข้อกำหนดของ OpenID คุณต้องใส่ค่าขอบเขต openid profile ในคำขอตรวจสอบสิทธิ์

หากต้องการรวมอีเมลของผู้ใช้ คุณสามารถระบุค่าขอบเขตเพิ่มเติมเป็น email ได้ หากต้องการระบุทั้ง profile และ email คุณสามารถใส่พารามิเตอร์ต่อไปนี้ใน URI คำขอการตรวจสอบสิทธิ์
```
scope=openid%20profile%20email
```
เพิ่มโทเค็นเพื่อการเข้าถึงลงในส่วนหัวของการให้สิทธิ์และส่งคำขอ HTTPS GET ไปยังปลายทาง userinfo ซึ่งคุณควรดึงข้อมูลจากเอกสารการค้นพบโดยใช้ค่าข้อมูลเมตา userinfo_endpoint การตอบกลับ userinfo จะมีข้อมูลเกี่ยวกับผู้ใช้ตามที่อธิบายไว้ใน OpenID Connect Standard Claims และค่าข้อมูลเมตา claims_supported ของเอกสารการค้นพบ ผู้ใช้หรือองค์กรของผู้ใช้อาจเลือกที่จะระบุหรือระงับข้อมูลในบางช่อง ดังนั้นคุณจึงอาจไม่ได้รับข้อมูลสำหรับทุกช่องในขอบเขตการเข้าถึงที่ได้รับอนุญาต

เอกสารการค้นพบ

โปรโตคอล OpenID Connect กำหนดให้ใช้ปลายทางหลายรายการเพื่อตรวจสอบสิทธิ์ผู้ใช้ และเพื่อขอทรัพยากรต่างๆ ซึ่งรวมถึงโทเค็น ข้อมูลผู้ใช้ และคีย์สาธารณะ

OpenID Connect ช่วยให้ใช้ "เอกสารการค้นพบ" ได้เพื่อลดความซับซ้อนในการติดตั้งใช้งานและเพิ่มความยืดหยุ่น ซึ่งเป็นเอกสาร JSON ที่พบในตำแหน่งที่รู้จักกันดีซึ่งมีคู่คีย์-ค่าที่ให้รายละเอียดเกี่ยวกับการกำหนดค่าของผู้ให้บริการ OpenID Connect รวมถึง URI ของปลายทางการให้สิทธิ์ โทเค็น การเพิกถอน ข้อมูลผู้ใช้ และคีย์สาธารณะ คุณสามารถเรียกดูเอกสารการค้นพบสำหรับบริการ OpenID Connect ของ Google ได้จาก

https://accounts.google.com/.well-known/openid-configuration

หากต้องการใช้บริการ OpenID Connect ของ Google คุณควรฮาร์ดโค้ด URI ของเอกสารการค้นพบ (https://accounts.google.com/.well-known/openid-configuration) ลงในแอปพลิเคชัน แอปพลิเคชันจะดึงข้อมูลเอกสาร ใช้กฎการแคชในการตอบกลับ แล้วดึงข้อมูล URI ของปลายทางจากเอกสารตามต้องการ ตัวอย่างเช่น หากต้องการตรวจสอบสิทธิ์ผู้ใช้ โค้ดของคุณจะดึงค่าข้อมูลเมตา authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth ในตัวอย่างด้านล่าง) เป็น URI พื้นฐานสำหรับคำขอตรวจสอบสิทธิ์ที่ส่งไปยัง Google

ต่อไปนี้เป็นตัวอย่างของเอกสารดังกล่าว โดยชื่อฟิลด์จะเป็นชื่อที่ระบุไว้ใน OpenID Connect Discovery 1.0 (โปรดดูความหมายในเอกสารดังกล่าว) ค่าเหล่านี้เป็นเพียงภาพประกอบและอาจมีการเปลี่ยนแปลง แม้ว่าจะคัดลอกมาจากเอกสาร Google Discovery เวอร์ชันล่าสุดก็ตาม

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

คุณอาจหลีกเลี่ยงการส่งไปกลับของ HTTP ได้โดยการแคชค่าจากเอกสารการค้นพบ ระบบจะใช้ส่วนหัวการแคช HTTP มาตรฐานและควรปฏิบัติตาม

ไลบรารีของไคลเอ็นต์

ไลบรารีของไคลเอ็นต์ต่อไปนี้ช่วยให้การติดตั้งใช้งาน OAuth 2.0 ง่ายขึ้นด้วยการผสานรวมกับเฟรมเวิร์กยอดนิยม

การปฏิบัติตามข้อกำหนดของ OpenID Connect

ระบบการตรวจสอบสิทธิ์ OAuth 2.0 ของ Google รองรับฟีเจอร์ที่จำเป็นของข้อกำหนด OpenID Connect Core ไคลเอ็นต์ที่ออกแบบมาเพื่อทำงานร่วมกับ OpenID Connect ควรทำงานร่วมกับบริการนี้ได้ (ยกเว้น OpenID Request Object)

OpenID Connect จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

การตั้งค่า OAuth 2.0

รับข้อมูลเข้าสู่ระบบ OAuth 2.0

ตั้งค่า URI การเปลี่ยนเส้นทาง

ปรับแต่งหน้าจอขอความยินยอมจากผู้ใช้

การเข้าถึงบริการ

การตรวจสอบสิทธิ์ผู้ใช้

โฟลว์เซิร์ฟเวอร์

1. สร้างโทเค็นสถานะป้องกันการปลอมแปลง

PHP

Java

Python

2. ส่งคำขอการตรวจสอบสิทธิ์ไปยัง Google

3. ยืนยันโทเค็นสถานะการป้องกันการปลอมแปลง

PHP

Java

Python

4. แลกเปลี่ยน code เป็นโทเค็นเพื่อการเข้าถึงและโทเค็นระบุตัวตน

5. รับข้อมูลผู้ใช้จากโทเค็นระบุตัวตน

เพย์โหลดของโทเค็นระบุตัวตน

6. ตรวจสอบสิทธิ์ผู้ใช้

หัวข้อขั้นสูง

สิทธิ์เข้าถึง Google APIs อื่นๆ

โทเค็นการรีเฟรช

การแจ้งขอความยินยอมอีกครั้ง

พารามิเตอร์ URI ของการตรวจสอบสิทธิ์

การตรวจสอบความถูกต้องของโทเค็นระบุตัวตน

การรับข้อมูลโปรไฟล์ผู้ใช้

เอกสารการค้นพบ

ไลบรารีของไคลเอ็นต์

การปฏิบัติตามข้อกำหนดของ OpenID Connect

OpenID Connect

4. แลกเปลี่ยน `code` เป็นโทเค็นเพื่อการเข้าถึงและโทเค็นระบุตัวตน