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 โดยทำดังนี้

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

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

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

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

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

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

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

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

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

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

1. เปิดหน้าการสร้างแบรนด์ในคอนโซล Google Cloud
2. หากได้รับข้อความแจ้ง ให้เลือกโปรเจ็กต์หรือสร้างโปรเจ็กต์ใหม่
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 Identity Services

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

ตร���จสอบว่าคุณได้ตั้งค่าแอปใน 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

ขั้นตอนถ��ดไปคือการสร้างคำขอ 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

// 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//developers.google.com/oauthplayground&
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 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 ยอมรับ

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

คุณต้องตรวจสอบโทเค็นระบุตัวตนทั้งหมดในเซิร์ฟเวอร์ เว้นแต่คุณจะทราบว่าโทเค็นเหล่านั้นมาจาก 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. เพิ่มโทเค็นเพื่อการเข้าถึงลงในส่วนหัวของการให้สิทธิ์และส่งคำขอ 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 ง่ายขึ้นด้วยการผสานรวมกับเฟ������วิร์กยอดนิยม

• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Java
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Python
• ไลบรารีของไคลเอ็นต์ Google APIs สำหร���บ .NET
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Ruby
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ PHP
• ไลบรารี OAuth 2.0 สำหรับ Google Web Toolkit
• Google Toolbox สำหรับ Mac OAuth 2.0 Controllers

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

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