Mỗi Hành động smart home phải bao gồm một cơ chế để xác thực người dùng.
Xác thực cho phép bạn liên kết tài khoản Google của người dùng với tài khoản người dùng trong hệ thống xác thực của bạn. Điều này cho phép bạn xác định người dùng khi phương thức thực hiện đơn hàng của bạn nhận được ý định nhà thông minh. Nhà thông minh của Google chỉ hỗ trợ OAuth bằng một quy trình mã ủy quyền.
Trang này mô tả cách thiết lập máy chủ OAuth 2.0 để máy chủ hoạt động với Hành động smart home.
Liên kết Tài khoản Google với OAuth
Trong quy trình mã ủy quyền, bạn cần có 2 điểm cuối:
Điểm cuối ủy quyền, hiển thị giao diện người dùng đăng nhập cho người dùng chưa đăng nhập. Điểm cuối ủy quyền cũng tạo một mã ủy quyền ngắn hạn để ghi lại sự đồng ý của người dùng đối với quyền truy cập đã yêu cầu.
Điểm cuối token exchange chịu trách nhiệm về hai loại trao đổi:
- Trao đổi một mã ủy quyền để lấy mã làm mới trong thời gian dài và một mã truy cập ngắn hạn. Quá trình trao đổi này diễn ra khi người dùng trải qua quy trình liên kết tài khoản.
- Trao đổi mã làm mới trong thời gian dài để lấy mã truy cập ngắn hạn. Quá trình trao đổi này diễn ra khi Google cần một mã truy cập mới vì mã này đã hết hạn.
Hướng dẫn thiết kế
Phần này mô tả các yêu cầu và đề xuất thiết kế đối với màn hình người dùng mà bạn lưu trữ cho các luồng liên kết OAuth. Sau khi ứng dụng của Google gọi tên, nền tảng của bạn sẽ hiển thị một màn hình đăng nhập vào trang Google và màn hình đồng ý liên kết tài khoản cho người dùng. Người dùng được chuyển hướng trở lại ứng dụng của Google sau khi đồng ý với các tài khoản liên kết.

Yêu cầu
- Bạn phải thông báo rằng tài khoản của người dùng sẽ được liên kết với Google, chứ không phải một sản phẩm cụ thể của Google như Google Home hoặc Trợ lý Google.
- Bạn phải có tuyên bố ủy quyền của Google, chẳng hạn như "Bằng cách đăng nhập, bạn đang ủy quyền cho Google kiểm soát thiết bị của bạn". Hãy xem phần Ủy quyền kiểm soát thiết bị của Google trong Chính sách dành cho nhà phát triển Google Home.
Đề xuất
Bạn nên thực hiện những việc sau:
Hiển thị Chính sách quyền riêng tư của Google. Cung cấp một đường liên kết đến Chính sách quyền riêng tư của Google trên màn hình xin phép.
Dữ liệu cần chia sẻ. Sử dụng ngôn ngữ rõ ràng và súc tích để cho người dùng biết dữ liệu của họ yêu cầu là gì và tại sao.
Lời kêu gọi hành động rõ ràng. Trình bày lời kêu gọi hành động rõ ràng trên màn hình đồng ý, chẳng hạn như “Đồng ý và liên kết”. Điều này là do người dùng cần hiểu rõ những dữ liệu nào cần phải chia sẻ với Google để liên kết tài khoản.
Khả năng huỷ. Cung cấp cho người dùng một cách để quay lại hoặc huỷ, nếu họ chọn không liên kết.
Xóa quy trình đăng nhập. Đảm bảo rằng người dùng có phương thức rõ ràng để đăng nhập vào Tài khoản Google của họ, chẳng hạn như các trường cho tên người dùng và mật khẩu hoặc Đăng nhập bằng Google.
Khả năng hủy liên kết. Cung cấp một cơ chế để người dùng huỷ liên kết, chẳng hạn như URL đến chế độ cài đặt tài khoản của họ trên nền tảng của bạn. Ngoài ra, bạn có thể bao gồm một đường liên kết đến Tài khoản Google để người dùng có thể quản lý tài khoản được liên kết.
Khả năng thay đổi tài khoản người dùng. Đề xuất một phương thức để người dùng chuyển đổi(các) tài khoản của họ. Điều này đặc biệt có lợi nếu người dùng có xu hướng có nhiều tài khoản.
- Nếu người dùng phải đóng màn hình xin phép để chuyển đổi tài khoản, hãy gửi lỗi có thể khôi phục cho Google để người dùng có thể đăng nhập vào tài khoản mong muốn bằng tính năng Liên kết OAuth.
Thêm biểu trưng của bạn. Hiển thị biểu trưng của công ty bạn trên màn hình xin phép. Sử dụng nguyên tắc kiểu của bạn để đặt biểu trưng. Nếu bạn cũng muốn hiển thị biểu trưng của Google, hãy xem Biểu trưng và nhãn hiệu.

Luồng mã ủy quyền
Quá trình triển khai máy chủ OAuth 2.0 cho quy trình mã uỷ quyền bao gồm hai điểm cuối mà dịch vụ của bạn cung cấp bằng HTTPS. Điểm cuối đầu tiên là điểm cuối ủy quyền, chịu trách nhiệm tìm hoặc lấy sự đồng ý của người dùng để có quyền truy cập vào dữ liệu. Điểm cuối ủy quyền cung cấp giao diện người dùng đăng nhập cho người dùng chưa đăng nhập và ghi lại sự đồng ý đối với quyền truy cập đã yêu cầu. Điểm cuối thứ hai là điểm cuối trao đổi mã thông báo, dùng để lấy các chuỗi đã mã hoá (gọi là mã thông báo) cho phép người dùng truy cập vào dịch vụ.
Khi một ứng dụng của Google cần gọi một trong các API của dịch vụ, Google sẽ sử dụng các điểm cuối này cùng nhau để người dùng của bạn cho phép gọi các API này thay cho họ.
Phiên quy trình mã uỷ quyền OAuth 2.0 do Google khởi tạo có quy trình sau:
- Google sẽ mở điểm cuối ủy quyền của bạn trong trình duyệt của người dùng. Nếu quy trình bắt đầu trên thiết bị chỉ có giọng nói cho một Hành động, Google sẽ chuyển quá trình thực thi sang điện thoại.
- Người dùng đăng nhập, nếu chưa đăng nhập và cấp cho Google quyền truy cập vào dữ liệu của họ bằng API của bạn, nếu họ chưa cấp quyền.
- Dịch vụ của bạn sẽ tạo một mã uỷ quyền và trả lại cho Google. Để làm vậy, hãy chuyển hướng trình duyệt của người dùng đó trở lại Google bằng mã uỷ quyền được đính kèm với yêu cầu.
- Google sẽ gửi mã uỷ quyền đến điểm cuối trao đổi mã thông báo của bạn để xác minh tính xác thực của mã và trả về mã truy cập và mã làm mới. Mã truy cập là một mã thông báo ngắn hạn mà dịch vụ của bạn chấp nhận làm thông tin xác thực để truy cập các API. Mã làm mới là một mã thông báo dài hạn mà Google có thể lưu trữ và sử dụng để lấy mã truy cập mới khi hết hạn.
- Sau khi người dùng hoàn tất quy trình liên kết tài khoản, mọi yêu cầu tiếp theo được gửi từ Google đều chứa mã truy cập.
Xử lý yêu cầu cấp quyền
Khi bạn cần liên kết tài khoản bằng quy trình mã uỷ quyền OAuth 2.0, Google sẽ gửi cho người dùng điểm cuối ủy quyền của bạn bằng một yêu cầu bao gồm các tham số sau:
Thông số điểm cuối ủy quyền | |
---|---|
client_id |
Mã khách hàng mà bạn đã chỉ định cho Google. |
redirect_uri |
URL mà bạn gửi phản hồi tới yêu cầu này. |
state |
Một giá trị sổ sách được trả về cho Google không thay đổi trong URI chuyển hướng. |
scope |
Không bắt buộc: Một tập hợp các chuỗi phạm vi được phân tách bằng dấu cách chỉ định dữ liệu mà Google đang yêu cầu ủy quyền. |
response_type |
Loại giá trị được trả về trong phản hồi. Đối với quy trình mã uỷ quyền OAuth 2.0, loại phản hồi luôn là code .
|
user_locale |
Chế độ cài đặt ngôn ngữ trong Tài khoản Google ở định dạng RFC5646, được dùng để bản địa hoá nội dung của bạn bằng ngôn ngữ ưu tiên của người dùng. |
Ví dụ: nếu điểm cuối ủy quyền của bạn có tại https://myservice.example.com/auth
, yêu cầu có thể có dạng như sau:
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
Để điểm cuối ủy quyền của bạn xử lý các yêu cầu đăng nhập, hãy làm theo các bước sau:
- Xác minh rằng
client_id
khớp với Mã ứng dụng khách mà bạn đã chỉ định cho Google vàredirect_uri
khớp với URL chuyển hướng do Google cung cấp cho dịch vụ của bạn. Các bước kiểm tra này rất quan trọng để ngăn việc cấp quyền truy cập vào các ứng dụng khách không mong muốn hoặc bị định cấu hình sai. Nếu bạn hỗ trợ nhiều flow 2.0 của OAuth, hãy xác nhận rằngresponse_type
đó làcode
. - Kiểm tra xem người dùng có đăng nhập vào dịch vụ của bạn hay không. Nếu người dùng chưa đăng nhập, hãy hoàn tất quy trình đăng nhập hoặc đăng ký dịch vụ của bạn.
- Tạo mã uỷ quyền để Google truy cập vào API của bạn. Mã uỷ quyền có thể là giá trị chuỗi bất kỳ, nhưng mã này phải đại diện riêng cho người dùng, ứng dụng khách cho mã thông báo và thời gian hết hạn của mã cũng như không thể đoán được. Thông thường, bạn sẽ phát hành mã uỷ quyền sẽ hết hạn sau khoảng 10 phút.
- Xác nhận rằng URL do thông số
redirect_uri
chỉ định có dạng như sau:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- Chuyển hướng trình duyệt của người dùng đến URL được xác định bởi thông số
redirect_uri
. Bao gồm mã uỷ quyền bạn vừa tạo và giá trị trạng thái ban đầu, chưa sửa đổi khi bạn chuyển hướng bằng cách thêm các tham sốcode
vàstate
. Sau đây là ví dụ về URL kết quả:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
Xử lý yêu cầu trao đổi mã thông báo
Điểm cuối trao đổi mã thông báo dịch vụ của bạn chịu trách nhiệm về hai loại trao đổi mã thông báo:
- Trao đổi mã ủy quyền cho mã truy cập và mã làm mới
- Trao đổi mã làm mới cho mã thông báo truy cập
Yêu cầu trao đổi mã thông báo bao gồm các thông số sau:
Thông số điểm cuối trao đổi mã thông báo | |
---|---|
client_id |
Chuỗi xác định nguồn gốc yêu cầu là Google. Chuỗi này phải được đăng ký trong hệ thống của bạn dưới dạng giá trị nhận dạng duy nhất của Google. |
client_secret |
Chuỗi bí mật mà bạn đã đăng ký với Google cho dịch vụ của mình. |
grant_type |
Loại mã thông báo đang được trao đổi. Đó là authorization_code hoặc refresh_token . |
code |
Khi grant_type=authorization_code , tham số này là mã mà Google nhận được từ điểm cuối đăng nhập hoặc
sàn giao dịch mã thông báo của bạn. |
redirect_uri |
Khi grant_type=authorization_code , tham số này là URL được sử dụng trong yêu cầu ủy quyền ban đầu. |
refresh_token |
Khi grant_type=refresh_token , thông số này là
mã làm mới mà Google nhận được từ điểm cuối trao đổi mã thông báo của bạn. |
Trao đổi mã ủy quyền cho mã truy cập và mã làm mới
Sau khi người dùng đăng nhập và điểm cuối ủy quyền của bạn trả về mã ủy quyền ngắn hạn cho Google, Google sẽ gửi yêu cầu đến điểm cuối trao đổi mã thông báo của bạn để đổi mã ủy quyền cho mã thông báo truy cập và mã thông báo làm mới.
Đối với những yêu cầu này, giá trị của grant_type
là authorization_code
và giá trị của code
là giá trị của mã ủy quyền bạn đã cấp cho Google trước đó. Sau đây là ví dụ về yêu cầu trao đổi mã uỷ quyền cho mã truy cập và mã làm mới:
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
Để trao đổi mã uỷ quyền cho mã truy cập và mã làm mới, điểm cuối trao đổi mã thông báo sẽ phản hồi các yêu cầu POST
bằng cách thực hiện các bước sau:
- Xác minh rằng
client_id
xác định nguồn gốc yêu cầu là một nguồn gốc được phép vàclient_secret
khớp với giá trị dự kiến. - Xác minh rằng mã uỷ quyền hợp lệ và chưa hết hạn, đồng thời xác định rằng Client-ID được chỉ định trong yêu cầu khớp với mã khách hàng liên kết với mã uỷ quyền.
- Xác nhận rằng URL do thông số
redirect_uri
chỉ định giống hệt với giá trị dùng trong yêu cầu uỷ quyền ban đầu. - Nếu bạn không thể xác minh tất cả các tiêu chí trên, hãy trả về lỗi Yêu cầu HTTP 400 với
{"error": "invalid_grant"}
là nội dung. - Nếu không, hãy sử dụng mã nhận dạng khách hàng từ mã uỷ quyền để tạo mã thông báo làm mới và mã thông báo truy cập. Các mã thông báo này có thể là bất kỳ giá trị chuỗi nào, nhưng phải biểu thị duy nhất người dùng và ứng dụng mà mã thông báo dành cho chúng, đồng thời không thể đoán được mã. Đối với mã truy cập, hãy ghi lại thời gian hết hạn của mã thông báo (thường là một giờ sau khi bạn cấp mã thông báo). Mã thông báo làm mới không hết hạn.
- Trả về đối tượng JSON sau trong phần nội dung của phản hồi HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Google lưu trữ mã truy cập và mã làm mới cho người dùng rồi ghi lại thời điểm mã thông báo truy cập hết hạn. Khi mã truy cập hết hạn, Google sẽ sử dụng mã làm mới để lấy mã truy cập mới từ điểm cuối trao đổi mã thông báo.
Trao đổi mã làm mới cho mã thông báo truy cập
Khi mã truy cập hết hạn, Google sẽ gửi yêu cầu đến điểm cuối trao đổi mã thông báo của bạn để trao đổi mã làm mới cho mã thông báo truy cập mới.
Đối với những yêu cầu này, giá trị của grant_type
là refresh_token
và giá trị của refresh_token
là giá trị của mã thông báo làm mới mà bạn đã cấp cho Google trước đây. Sau đây là ví dụ về yêu cầu đổi mã thông báo làm mới
cho mã truy cập:
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
Để trao đổi mã làm mới cho mã thông báo truy cập, điểm cuối trao đổi mã thông báo sẽ phản hồi các yêu cầu POST
bằng cách thực thi các bước sau:
- Xác minh rằng
client_id
xác định nguồn gốc của yêu cầu là Google vàclient_secret
khớp với giá trị dự kiến. - Xác minh rằng mã thông báo làm mới là hợp lệ và mã ứng dụng khách được chỉ định trong yêu cầu khớp với mã ứng dụng khách liên kết với mã thông báo làm mới.
- Nếu bạn không thể xác minh tất cả các tiêu chí trên, hãy trả về lỗi Yêu cầu HTTP 400 có nội dung là
{"error": "invalid_grant"}
. - Nếu không, hãy sử dụng mã nhận dạng khách hàng từ mã làm mới để tạo mã truy cập. Các mã thông báo này có thể là giá trị chuỗi bất kỳ, nhưng phải duy nhất đại diện cho người dùng và ứng dụng mà mã thông báo dành cho và không được dự đoán. Đối với mã truy cập, hãy ghi lại thời gian hết hạn của mã thông báo, thường là một giờ sau khi bạn phát hành mã thông báo.
- Trả về đối tượng JSON sau trong phần nội dung của phản hồi HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Xử lý yêu cầu cung cấp thông tin người dùng
Điểm cuối người dùng là một tài nguyên được bảo vệ bằng OAuth 2.0 trả về các xác nhận quyền sở hữu về người dùng được liên kết. Bạn không bắt buộc phải triển khai và lưu trữ điểm cuối userinfo, ngoại trừ các trường hợp sử dụng sau đây:
- Đăng nhập vào tài khoản được liên kết bằng Google One Tap.
- Gói thuê bao tiện dụng trên AndroidTV.
Sau khi bạn đã truy xuất mã thông báo truy cập thành công từ điểm cuối mã thông báo, Google sẽ gửi yêu cầu đến điểm cuối thông tin người dùng để truy xuất thông tin hồ sơ cơ bản về người dùng được liên kết.
tiêu đề của yêu cầu điểm cuối userinfo | |
---|---|
Authorization header |
Mã truy cập của loại Bearer. |
Ví dụ: nếu điểm cuối userinfo của bạn có tại https://myservice.example.com/userinfo
, yêu cầu có thể có dạng như sau:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
Để điểm cuối userinfo xử lý các yêu cầu, hãy làm theo các bước sau:
- Trích xuất mã truy cập từ tiêu đề Uỷ quyền và thông tin trả về dành cho người dùng đã liên kết với mã truy cập.
- Nếu mã truy cập không hợp lệ, hãy trả về lỗi HTTP 401 Không được phép bằng cách sử dụng Tiêu đề phản hồi
WWW-Authenticate
. Dưới đây là ví dụ về phản hồi của thông tin người dùng:HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
Nếu lỗi 401 chưa được uỷ quyền hoặc bất kỳ phản hồi lỗi nào không thành công được trả về trong quá trình liên kết, thì lỗi này sẽ không thể khôi phục, mã thông báo đã truy xuất sẽ bị huỷ và người dùng sẽ phải bắt đầu lại quá trình liên kết. Nếu mã truy cập là hợp lệ, hãy trả về và phản hồi HTTP 200 với đối tượng JSON sau trong phần nội dung của phản hồi HTTPS:
{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
Nếu điểm cuối userinfo trả về một phản hồi thành công qua HTTP 200, thì mã thông báo và các thông báo xác nhận quyền sở hữu đã được truy xuất sẽ được đăng ký cho Tài khoản Google của người dùng.phản hồi của điểm cuối userinfo sub
Mã nhận dạng duy nhất xác định người dùng trong hệ thống của bạn. email
Địa chỉ email của người dùng. given_name
Không bắt buộc: Tên của người dùng. family_name
Không bắt buộc: Họ của người dùng. name
Không bắt buộc: Tên đầy đủ của người dùng. picture
Không bắt buộc: Ảnh hồ sơ của người dùng.