การดําเนินการsmart homeทุกๆ รายการต้องมีกลไกสําหรับการตรวจสอบสิทธิ์ผู้ใช้
การตรวจสอบสิทธิ์ช่วยให้คุณลิงก์บัญชี Google ของผู้ใช้กับบัญชีผู้ใช้ในระบบการตรวจสอบสิทธิ์ได้ ซึ่งจะช่วยให้คุณระบุผู้ใช้ได้เมื่อดําเนินการตามคําสั่งซื้อสมาร์ทโฮม บ้านอัจฉริยะของ Google รองรับเฉพาะ OAuth พร้อมขั้นตอนการให้สิทธิ์รหัสการให้สิทธิ์เท่านั้น
หน้านี้อธิบายวิธีตั้งค่าเซิร์ฟเวอร์ OAuth 2.0 เพื่อทํางานกับการดําเนินการ smart home ของคุณ
โฟลว์รหัสการให้สิทธิ์
การดําเนินการของเซิร์ฟเวอร์ OAuth 2.0 ตามโฟลว์รหัสการให้สิทธิ์ประกอบด้วยปลายทาง 2 ปลายทาง ซึ่งบริการจะเปิดเผยด้วย HTTPS ปลายทางแรกคือปลายทางการให้สิทธิ์ ซึ่งมีหน้าที่ในการค้นหาหรือขอความยินยอมจากผู้ใช้สําหรับการเข้าถึงข้อมูล ปลายทางการให้สิทธิ์จะแสดง UI การลงชื่อเข้าใช้แก่ผู้ใช้ที่ไม่ได้ลงชื่อเข้าใช้และบันทึกความยินยอมสําหรับการเข้าถึงที่ขอ ปลายทางที่ 2 คือปลายทางการแลกเปลี่ยนโทเค็นซึ่งใช้เพื่อรับสตริงที่เข้ารหัสที่เรียกว่าโทเค็น ซึ่งให้สิทธิ์ผู้ใช้เข้าถึงบริการของคุณ
เมื่อแอปพลิเคชันของ Google ต้องเรียก API บริการใดบริการหนึ่งของคุณ Google จะใช้ปลายทางเหล่านี้ร่วมกันเพื่อขอสิทธิ์จากผู้ใช้ในการเรียก API เหล่านี้ในนามของ API
เซสชันโฟลว์ของรหัสการให้สิทธิ์ OAuth 2.0 ที่ Google เริ่มต้นมีขั้นตอนดังนี้
- Google เปิดปลายทางการให้สิทธิ์ในเบราว์เซอร์ของผู้ใช้ หากขั้นตอนเริ่มต้นในอุปกรณ์ที่มีเสียงเท่านั้นสําหรับการดําเนินการ Google จะโอนคําสั่งไปยังโทรศัพท์
- หากผู้ใช้ยังไม่ได้ลงชื่อเข้าใช้และให้สิทธิ์ Google ในการเข้าถึงข้อมูลด้วย API ของคุณ หากผู้ใช้ยังไม่ได้ให้สิทธิ์
- บริการจะสร้างรหัสการให้สิทธิ์และส่งไปยัง Google ในการดําเนินการดังกล่าว ให้เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้กลับไปยัง Google พร้อมรหัสการให้สิทธิ์ที่แนบมากับคําขอ
- Google จะส่งรหัสการให้สิทธิ์ไปยังปลายทางการแลกเปลี่ยนโทเค็นของคุณ ซึ่งจะตรวจสอบความถูกต้องของโค้ดและแสดงผลโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช โทเค็นเพื่อการเข้าถึงคือโทเค็นที่มีอายุสั้นที่บริการของคุณยอมรับเป็นข้อมูลเข้าสู่ระบบเพื่อเข้าถึง API โทเค็นการรีเฟรชเป็นโทเค็นที่มีอายุยาวนาน ที่ Google จะจัดเก็บและใช้เพื่อให้ได้โทเค็นเพื่อการเข้าถึงใหม่เมื่อโทเค็นหมดอายุ
- หลังจากที่ผู้ใช้ทําการลิงก์บัญชีแล้ว คําขอที่ตามมาทั้งหมดจาก Google จะส่งโทเค็นเพื่อการเข้าถึง
จัดการคําขอการให้สิทธิ์
เมื่อคุณต้องการลิงก์บัญชีโดยใช้ขั้นตอนการให้สิทธิ์ OAuth 2.0 ทาง Google จะส่งผู้ใช้ไปยังปลายทางการให้สิทธิ์ที่มีคําขอซึ่งมีพารามิเตอร์ต่อไปนี้
พารามิเตอร์ปลายทางของการให้สิทธิ์ | |
---|---|
client_id |
รหัสไคลเอ็นต์ที่คุณกําหนดให้กับ Google |
redirect_uri |
URL ที่คุณส่งคําตอบสําหรับคําขอนี้ |
state |
ค่าการทําบัญชีที่ส่งกลับไปยัง Google จะไม่เปลี่ยนแปลงใน URI การเปลี่ยนเส้นทาง |
scope |
ไม่บังคับ: ชุดสตริงขอบเขตที่คั่นด้วยช่องว่างซึ่งระบุข้อมูลที่ Google ขอสิทธิ์ |
response_type |
ประเภทของค่าที่จะแสดงในการตอบกลับ สําหรับโฟลว์รหัสการให้สิทธิ์ OAuth 2.0 ประเภทการตอบกลับจะเป็น code เสมอ
|
user_locale |
การตั้งค่าภาษาในบัญชี Google ในรูปแบบ RFC5646 ที่ใช้ในการแปลเนื้อหาในภาษาที่ผู้ใช้ต้องการ |
ตัวอย่างเช่น หากปลายทางการให้สิทธิ์พร้อมใช้งานใน https://myservice.example.com/auth
คําขออาจมีลักษณะดังนี้
GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
หากต้องการให้ปลายทางการให้สิทธิ์จัดการคําขอลงชื่อเข้าใช้ ให้ทําตามขั้นตอนต่อไปนี้
- ยืนยันว่า
client_id
ตรงกับรหัสไคลเอ็นต์ที่คุณกําหนดให้กับ Google และredirect_uri
ตรงกับ URL เปลี่ยนเส้นทางที่ Google มีให้สําหรับบริการของคุณ การตรวจสอบเหล่านี้มีความสําคัญในการป้องกันการให้สิทธิ์ ในการเข้าถึงแอปไคลเอ็นต์โดยไม่ได้ตั้งใจหรือที่กําหนดค่าไม่ถูกต้อง หากคุณรองรับขั้นตอน OAuth 2.0 หลายชุด โปรดยืนยันว่าresponse_type
คือcode
- ตรวจสอบว่าผู้ใช้ลงชื่อเข้าใช้บริการของคุณหรือไม่ หากผู้ใช้ไม่ได้ลงชื่อเข้าใช้ ให้ลงชื่อเข้าใช้บริการหรือขั้นตอนการลงชื่อสมัครใช้ให้เสร็จสิ้น
- สร้างรหัสการให้สิทธิ์สําหรับ Google เพื่อใช้เข้าถึง API ของคุณ รหัสการให้สิทธิ์อาจเป็นสตริงใดก็ได้ แต่จะต้องแสดงถึงผู้ใช้ ไคลเอ็นต์ที่ใช้โทเค็น และรหัสวันหมดอายุ และต้องไม่คาดเดาได้ โดยปกติแล้ว คุณจะออกรหัสการให้สิทธิ์ที่จะหมดอายุภายใน 10 นาทีโดยประมาณ
- ยืนยันว่า URL ที่ระบุโดยพารามิเตอร์
redirect_uri
มีรูปแบบต่อไปนี้https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- เปลี่ยนเส้นทางเบราว์เซอร์ของผู้ใช้ไปยัง URL ที่ระบุโดยพารามิเตอร์
redirect_uri
ใส่รหัสการให้สิทธิ์ที่คุณเพิ่งสร้างขึ้น และค่าสถานะที่ไม่มีการปรับเปลี่ยนที่เป็นต้นฉบับเมื่อคุณเปลี่ยนเส้นทางโดยให้เพิ่มพารามิเตอร์code
และstate
ต่อท้าย ต่อไปนี้เป็นตัวอย่างของ URL ที่ได้:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
จัดการคําขอแลกเปลี่ยนโทเค็น
ปลายทางของการแลกเปลี่ยนโทเค็นของบริการมีหน้าที่รับผิดชอบการแลกเปลี่ยนโทเค็น 2 ประเภทดังนี้
- รหัสการให้สิทธิ์ของ Exchange สําหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช
- โทเค็นการรีเฟรช Exchange สําหรับโทเค็นเพื่อการเข้าถึง
คําขอการแลกเปลี่ยนโทเค็นมีพารามิเตอร์ต่อไปนี้
พารามิเตอร์ปลายทางการแลกเปลี่ยนโทเค็น | |
---|---|
client_id |
สตริงที่ระบุที่มาของคําขอเป็น Google สตริงนี้ต้องลงทะเบียนภายในระบบเป็นตัวระบุที่ไม่ซ้ํากันของ Google' |
client_secret |
สตริงลับที่คุณลงทะเบียนกับ Google สําหรับบริการของคุณ |
grant_type |
ประเภทของโทเค็นที่จะแลกเปลี่ยน หมายเลข authorization_code หรือ refresh_token |
code |
เมื่อ grant_type=authorization_code พารามิเตอร์นี้คือรหัสที่ Google ได้รับจากปลายทางการลงชื่อเข้าใช้หรือปลายทางการแลกเปลี่ยนโทเค็น |
redirect_uri |
เมื่อ grant_type=authorization_code พารามิเตอร์นี้คือ URL ที่ใช้ในคําขอการให้สิทธิ์ครั้งแรก |
refresh_token |
เมื่อ grant_type=refresh_token พารามิเตอร์นี้คือโทเค็นการรีเฟรชที่ Google ได้รับจากปลายทางการแลกเปลี่ยนโทเค็น |
รหัสการให้สิทธิ์ของ Exchange สําหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช
หลังจากที่ผู้ใช้ลงชื่อเข้าใช้และปลายทางการให้สิทธิ์ของคุณแสดงรหัสการให้สิทธิ์ในช่วงเวลาสั้นๆ ต่อ Google จะส่งคําขอไปยังปลายทางการแลกเปลี่ยนโทเค็นเพื่อแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช
สําหรับคําขอเหล่านี้ ค่าของ grant_type
คือ authorization_code
และค่าของ code
คือค่าของรหัสการให้สิทธิ์ที่คุณให้ไว้กับ Google ก่อนหน้านี้ ต่อไปนี้เป็นตัวอย่างคําขอแลกเปลี่ยน
รหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
หากต้องการแลกเปลี่ยนรหัสการให้สิทธิ์สําหรับโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรช ปลายทาง Exchange โทเค็นจะตอบกลับคําขอ POST
โดยทําตามขั้นตอนต่อไปนี้
- ยืนยันว่า
client_id
ระบุต้นทางคําขอเป็นต้นทางที่ได้รับอนุญาต และclient_secret
ตรงกับค่าที่คาดไว้ - ตรวจสอบว่ารหัสการให้สิทธิ์ถูกต้องและไม่หมดอายุ รวมถึงรหัสไคลเอ็นต์ที่ระบุในคําขอตรงกับรหัสไคลเอ็นต์ที่เชื่อมโยงกับรหัสการให้สิทธิ์
- ยืนยันว่า URL ที่ระบุโดยพารามิเตอร์
redirect_uri
เหมือนกับค่าที่ใช้ในคําขอการให้สิทธิ์เริ่มต้น - หากยืนยันเกณฑ์ทั้งหมดข้างต้นไม่ได้ ให้แสดงข้อผิดพลาดคําขอ HTTP 400 ที่ไม่ถูกต้องโดยมี
{"error": "invalid_grant"}
เป็นเนื้อความ - ไม่เช่นนั้น ให้ใช้รหัสผู้ใช้จากรหัสการให้สิทธิ์เพื่อสร้างโทเค็นการรีเฟรชและโทเค็นเพื่อการเข้าถึง โทเค็นเหล่านี้อาจเป็นสตริงใดก็ได้ แต่โทเค็นนี้ต้องแสดงถึงผู้ใช้และไคลเอ็นต์สําหรับโทเค็นโดยเฉพาะ และต้องไม่คาดเดาได้ สําหรับโทเค็นเพื่อการเข้าถึง ให้บันทึกเวลาหมดอายุของโทเค็น ซึ่งโดยทั่วไปคือ 1 ชั่วโมงหลังจากออกโทเค็น โทเค็นการรีเฟรชก็จะไม่หมดอายุ
- แสดงผลออบเจ็กต์ JSON ต่อไปนี้ในส่วนเนื้อหาของการตอบกลับ HTTPS
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Google จะจัดเก็บโทเค็นเพื่อการเข้าถึงและโทเค็นการรีเฟรชให้ผู้ใช้และบันทึกโทเค็นที่หมดอายุ เมื่อโทเค็นเพื่อการเข้าถึงหมดอายุ Google จะใช้โทเค็นการรีเฟรช เพื่อรับโทเค็นเพื่อการเข้าถึงใหม่จากปลายทางการแลกเปลี่ยนโทเค็น
โทเค็นการรีเฟรช Exchange สําหรับโทเค็นเพื่อการเข้าถึง
เมื่อโทเค็นเพื่อการเข้าถึงหมดอายุ Google จะส่งคําขอไปยังปลายทางการแลกเปลี่ยนโทเค็นเพื่อแลกเปลี่ยนโทเค็นการรีเฟรชสําหรับโทเค็นเพื่อการเข้าถึงใหม่
สําหรับคําขอเหล่านี้ ค่าของ grant_type
คือ refresh_token
และค่าของ refresh_token
คือค่าของโทเค็นการรีเฟรชที่คุณมอบให้แก่ Google ก่อนหน้านี้ ต่อไปนี้เป็นตัวอย่างคําขอแลกเปลี่ยนโทเค็นการรีเฟรช
สําหรับโทเค็นเพื่อการเข้าถึง
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
หากต้องการแลกเปลี่ยนโทเค็นการรีเฟรชสําหรับโทเค็นการเข้าถึง ปลายทางการแลกเปลี่ยนโทเค็นจะสอดคล้องกับคําขอ POST
โดยปฏิบัติตามขั้นตอนต่อไปนี้
- ยืนยันว่า
client_id
ระบุต้นทางคําขอเป็น Google และclient_secret
ตรงกับค่าที่คาดไว้ - ตรวจสอบว่าโทเค็นการรีเฟรชถูกต้อง และรหัสไคลเอ็นต์ที่ระบุในคําขอตรงกับรหัสไคลเอ็นต์ที่เชื่อมโยงกับโทเค็นการรีเฟรช
- หากยืนยันเกณฑ์ทั้งหมดข้างต้นไม่ได้ ให้แสดงข้อผิดพลาดคําขอ HTTP 400 ที่ไม่ถูกต้องโดยมี
{"error": "invalid_grant"}
เป็นเนื้อความ - ไม่เช่นนั้น ให้ใช้ User ID จากโทเค็นการรีเฟรชเพื่อสร้างโทเค็นเพื่อการเข้าถึง โดยโทเค็นเหล่านี้อาจเป็นค่าสตริงใดก็ได้ แต่ต้องแสดงถึงผู้ใช้และไคลเอ็นต์สําหรับโทเค็นโดยเฉพาะ และต้องไม่คาดเดาได้ สําหรับโทเค็นเพื่อการเข้าถึง ให้บันทึกเวลาหมดอายุของโทเค็นด้วย ซึ่งโดยทั่วไปคือใช้เวลา 1 ชั่วโมงหลังจากคุณออกโทเค็น
- แสดงผลออบเจ็กต์ JSON ต่อไปนี้ในส่วนเนื้อหาของการตอบกลับ HTTPS
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Handle userinfo requests
The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:
- Linked Account Sign-In with Google One Tap.
- Frictionless subscription on AndroidTV.
After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.
userinfo endpoint request headers | |
---|---|
Authorization header |
The access token of type Bearer. |
For example, if your userinfo endpoint is available at
https://myservice.example.com/userinfo
, a request might look like the following:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
For your userinfo endpoint to handle requests, do the following steps:
- Extract access token from the Authorization header and return information for the user associated with the access token.
- If the access token is invalid, return an HTTP 401 Unauthorized error with using the
WWW-Authenticate
Response Header. Below is an example of a userinfo error response:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.userinfo endpoint response sub
A unique ID that identifies the user in your system. email
Email address of the user. given_name
Optional: First name of the user. family_name
Optional: Last name of the user. name
Optional: Full name of the user. picture
Optional: Profile picture of the user.