OpenID Connect

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

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

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

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

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

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

หรือดูรหัสลูกค้าและข้อมูลลับลูกค้าของคุณจาก หน้าข้อมูลรับรอง ใน API Console :

1. Go to the Credentials page.
2. คลิกที่ชื่อหนังสือรับรองของคุณหรือไอคอนดินสอ ( create ) รหัสลูกค้าและความลับของคุณอยู่ที่ด้านบนของหน้า

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

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

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

1. Go to the Credentials page.
2. ในส่วน รหัสลูกค้า OAuth 2.0 ของหน้าคลิกข้อมูลรับรอง
3. ดูหรือแก้ไข URIs การเปลี่ยนเส้นทาง

หากไม่มีส่วน รหัสลูกค้า OAuth 2.0 ในหน้าหนังสือรับรองแสดงว่าโครงการของคุณไม่มีข้อมูลรับรอง OAuth หากต้องการสร้างหนึ่งคลิก สร้างข้อมูลรับรอง

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

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

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

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

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

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

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

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

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

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

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

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

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

ขั้นตอนของเซิร์ฟเวอร์

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

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

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

คุณต้องปกป้องความปลอดภัยของผู้ใช้ด้วยการป้องกันการขอการโจมตีด้วยการปลอมแปลง ขั้นตอนแรกคือการสร้างโทเค็นเซสชันที่ไม่ซ้ำกันซึ่งเก็บสถานะระหว่างแอปและไคลเอ็นต์ของผู้ใช้ หลังจากนั้น คุณจับคู่โทเค็นเซสชันที่ไม่ซ้ำกันนี้กับการตอบกลับการตรวจสอบสิทธิ์ที่บริการเข้าสู่ระบบ OAuth ของ Google แสดงผลเพื่อยืนยันว่าผู้ใช้เป็นผู้ส่งคำขอ ไม่ใช่ผู้โจมตีที่เป็นอันตราย โทเค็นเหล่านี้มักเรียกว่าโทเค็นคำขอข้ามเว็บไซต์ (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 พื้นฐานจากเอกสาร Discovery โดยใช้ค่าข้อมูลเมตา authorization_endpoint การสนทนาต่อไปนี้จะถือว่า URI พื้นฐานคือ https://accounts.google.com/o/oauth2/v2/auth

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

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

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 ไปยังปลายทางของโทเค็น ซึ่งคุณควรเรียกดูจากเอกสาร Discovery โดยใช้ค่าข้อมูลเมตา 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 ในคำขอการตรวจสอบสิทธิ์

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

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

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

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

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

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

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

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

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

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

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

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

โทเค็นรหัสเป็นข้อมูลที่ละเอียดอ่อนและอาจถูกใช้ในทางที่ผิดหากมีการสกัดกั้น คุณต้องตรวจสอบว่าโทเค็นเหล่านี้ได้รับการจัดการอย่างปลอดภัยโดยส่งผ่าน 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 ของคีย์จากเอกสาร Discovery โดยใช้ค่าข้อมูลเมตา jwks_uri คำขอที่ส่งไปยังปลายทางการแก้ไขข้อบกพร่องอาจถูกควบคุมหรืออาจมีข้อผิดพลาดเป็นช่วงๆ

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

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

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

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

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

   scope=openid%20profile%20email

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

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

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

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

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

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