OpenID Connect

คุณใช้ Google OAuth 2.0 APIs ได้ทั้งสำหรับการตรวจสอบสิทธิ์และการให้สิทธิ์ เอกสารนี้ อธิบายการติดตั้งใช้งาน 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 Console เพื่อรับข้อมูลเข้าสู่ระบบ OAuth 2.0 ตั้งค่า URI การเปลี่ยนเส้นทาง และ (ไม่บังคับ) ปรับแต่งข้อมูลการสร้างแบรนด์ที่ผู้ใช้เห็นในหน้าจอคำยินยอมของผู้ใช้ นอกจากนี้ คุณยังใช้ Cloud Console เพื่อ สร้างบัญชีบริการ เปิดใช้การเรียกเก็บเงิน ตั้งค่าการกรอง และทํางานอื่นๆ ได้ด้วย ดูรายละเอียดเพิ่มเติมได้ที่ Google Cloud Console ความช่วยเหลือ

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

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

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

หรือดูรหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์จาก Clients page ใน Cloud Console

1. Go to the Clients page.
2. คลิกชื่อลูกค้าหรือไอคอนแก้ไข (create) รหัสไคลเอ็นต์และรหัสลับจะอยู่ที่ด้านบนของหน้า

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

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

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

1. Go to the Clients page.
2. คลิกลูกค้า
3. ดูหรือแก้ไข URI การเปลี่ยนเส้นทาง

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

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

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

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

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

1. เปิด Branding page ใน Google Cloud Console
2. If prompted, select a project, or create a new one.
3. กรอกแบบฟอร์มแล้วคลิกบันทึก

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// 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
));

// 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);

# 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

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

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

• client_id ซึ่งคุณได้รับจาก Cloud Console Clients page
• response_type ซึ่งในคำขอขั้นตอนรหัสการให้สิทธิ์พื้นฐานควรเป็น code (อ่านเพิ่มเติมที่ response_type)
• scope ซึ่งในคำขอพื้นฐานควรเป็น openid email (อ่านเพิ่มเติมที่ scope)
• redirect_uri ควรเป็นปลายทาง HTTP ในเซิร์ฟเวอร์ของคุณที่จะได้รับการตอบกลับจาก Google ค่าต้องตรงกับ URI การเปลี่ยนเส้นทางที่ได้รับอนุญาตสำหรับไคลเอ็นต์ OAuth 2.0 ซึ่งคุณกำหนดค่าไว้ใน Cloud Console Credentials pageหากค่านี้ไม่ตรงกับ 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//oauth2.example.com/code&
 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 ที่คุณระบุใน request ระบบจะแสดงคำตอบทั้งหมดในสตริงการค้นหา

https://oauth2.example.com/code?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

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

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

// 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);
}

// 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.");
}

# 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เนื้อหา

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

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//oauth2.example.com/code&
grant_type=authorization_code

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

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 อาจมีฟิลด์ต่อไปนี้ (เรียกว่าการอ้างสิทธิ์)

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

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

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

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

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

การเข้าถึง Google API อื่นๆ

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

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

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

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

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

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

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

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

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

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

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

การตรวจสอบโทเค็นรหัส

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

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

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

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

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

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

1. ตรวจสอบว่าโทเค็นรหัสได้รับการลงนามอย่างถูกต้องจากผู้ออก โทเค็นที่ Google ออกให้จะได้รับการลงนาม โดยใช้ใบรับรองรายการใดรายการหนึ่งที่พบใน URI ที่ระบุในค่าjwks_uriข้อมูลเมตา ของเอกสารการค้นพบ
2. ยืนยันว่าค่าของการอ้างสิทธิ์ iss ในโทเค็นรหัสเท่ากับ https://accounts.google.com หรือ accounts.google.com
3. ตรวจสอบว่าค่าของaudการอ้างสิทธิ์ในโทเค็นรหัสเท่ากับรหัสไคลเอ็นต์ของแอป
4. ตรวจสอบว่าเวลาหมดอายุ (อ้างสิทธิ์ exp) ของโทเค็นรหัสยังไม่หมดอายุ
5. หากคุณระบุค่าพารามิเตอร์ 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 ดังนี้

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

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

   scope=openid%20profile%20email

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

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

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

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

• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Python
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ .NET
• ไลบรารีของไคลเอ็นต์ Google API สำหรับ Ruby
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ PHP
• ไลบรารี OAuth 2.0 สำหรับ Google Web Toolkit
• ตัวควบคุม OAuth 2.0 ของกล่องเครื่องมือของ Google สำหรับ Mac

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

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