OpenID Connect

คุณสามารถใช้ OAuth 2.0 API ของ 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

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

1. Go to the Credentials page.
2. Click the name of your credential or the pencil (create) icon. Your client ID and secret are at the top of the page.

ตั้งค่า 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 API ตัวอย่าง ได้แก่ Google Identity Services และไลบรารีของไคลเอ็นต์ Google ซึ่งพร้อมให้บริการสำหรับแพลตฟอร์มต่างๆ

หากเลือกไม่ใช้ไลบรารี ให้ทําตามวิธีการในส่วนที่เหลือของเอกสารนี้ ซึ่งอธิบายขั้นตอนคําขอ HTTP ที่อยู่เบื้องหลังไลบรารีที่ใช้ได้

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

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

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

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

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

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

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

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

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

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 โดยตรง ตัวอย่างเช่น เซิร์ฟเวอร์ต้องยืนยันว่าโทเค็นระบุตัวตนที่ได้รับจากแอปไคลเอ็นต์เป็นของจริง

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

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

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

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

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

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

เอกสาร Discovery

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

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

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

หากต้องการใช้บริการ OpenID Connect ของ Google คุณควรเขียนโค้ด URI ของเอกสาร Discovery (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 API สำหรับ .NET
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ Ruby
• ไลบรารีของไคลเอ็นต์ Google APIs สำหรับ PHP
• ไลบรารี OAuth 2.0 สําหรับ Google Web Toolkit
• เครื่องมือของ Google สำหรับ Mac OAuth 2.0 Controllers

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

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