Triển khai máy chủ OAuth 2.0

Mọi hoạt động tích hợp Cloud-to-cloud đều phải có cơ chế xác thực người dùng.

Tính nă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 nhận được ý định về nhà thông minh. Nhà thông minh của Google chỉ hỗ trợ OAuth bằng quy trình mã uỷ quyền.

Trang này mô tả cách thiết lập máy chủ OAuth 2.0 để máy chủ này hoạt động với tính năng tích hợp Cloud-to-cloud.

Liên kết Tài khoản Google bằng OAuth

Trong quy trình mã uỷ quyền, bạn cần có 2 điểm cuối:

• Điểm cuối uỷ quyền này sẽ 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 uỷ quyền cũng tạo một mã uỷ 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 được yêu cầu.

• Điểm cuối trao đổi mã thông báo, chịu trách nhiệm cho 2 loại trao đổi:

  1. Trao đổi mã uỷ quyền lấy mã làm mới dài hạn và mã truy cập ngắn hạn. Quá trình trao đổi này xảy ra khi người dùng thực hiện quy trình liên kết tài khoản.
  2. Trao đổi mã làm mới dài hạn 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ã mà Google đã hết hạn.

Hướng dẫn thiết kế

Phần này mô tả các yêu cầu về thiết kế và đề xuất cho màn hình người dùng mà bạn lưu trữ cho quy trình liên kết OAuth. Sau khi được ứng dụng của Google gọi, nền tảng của bạn sẽ hiển thị màn hình đăng nhập vào trang Google và màn hình xin phép liên kết tài khoản cho người dùng. Người dùng sẽ được chuyển hướng trở lại ứng dụng của Google sau khi đồng ý liên kết tài khoản.

Yêu cầu

1. 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, không phải với một sản phẩm cụ thể của Google như Google Home hay Trợ lý Google.
2. Bạn phải có tuyên bố uỷ quyền của Google, chẳng hạn như "Bằng việc đăng nhập, bạn đang uỷ quyền cho Google điều khiển thiết bị của mình". Xem phần Uỷ 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.
3. Bạn phải cung cấp cho người dùng cách để quay lại hoặc huỷ liên kết nếu họ chọn không liên kết.
4. Bạn phải mở trang liên kết Web OAuth và đả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 để nhập tên người dùng và mật khẩu. Đừng sử dụng phương thức Đăng nhập bằng Google (GSI) cho phép người dùng liên kết mà không cần chuyển đến trang Liên kết OAuth trên web. Đây là hành vi vi phạm chính sách của Google.

Đề xuất

Bạn nên làm như sau:

1. Trình bày Chính sách quyền riêng tư của Google. Thêm 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.

2. Dữ liệu được chia sẻ. Sử dụng ngôn ngữ rõ ràng và súc tích để cho người dùng biết Google yêu cầu dữ liệu nào và lý do tại sao.

3. Xoá lời kêu gọi hành động. Hãy đưa ra lời kêu gọi hành động rõ ràng trên màn hình xin phép, chẳng hạn như “Đồng ý và liên kết”. Lý do là vì người dùng cần hiểu những dữ liệu mà họ cần phải chia sẻ với Google để liên kết tài khoản của họ.

4. Khả năng hủy liên kết. Cung cấp cơ chế để người dùng huỷ liên kết, chẳng hạn như URL đến phần 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 nơi người dùng có thể quản lý tài khoản được liên kết của họ.

5. Quyền 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.

6. Thêm biểu trưng của bạn. Hiển thị biểu trưng công ty của bạn trên màn hình đồng ý. Sử dụng nguyên tắc về kiểu cách để đặt biểu trưng. Nếu bạn muốn hiển thị cả biểu trưng của Google, hãy xem phần Biểu trưng và nhãn hiệu.

Quy trình sử dụng mã uỷ quyền

Quy trình triển khai máy chủ OAuth 2.0 của mã uỷ quyền bao gồm hai điểm cuối mà dịch vụ của bạn cung cấp qua HTTPS. Điểm cuối đầu tiên là điểm cuối uỷ quyền, chịu trách nhiệm tìm hoặc lấy sự đồng ý của người dùng để truy cập dữ liệu. Điểm cuối uỷ quyền hiển thị giao diện người dùng đăng nhập cho những người dùng chưa đăng nhập và ghi lại sự đồng ý đối với quyền truy cập được yêu cầu. Điểm cuối thứ hai là điểm cuối trao đổi mã thông báo, được 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ụ của bạn.

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 để yêu cầu người dùng cấp quyền thay mặt họ gọi các API này.

Phiên luồng mã uỷ quyền OAuth 2.0 do Google khởi tạo có quy trình sau:

1. Google sẽ mở điểm cuối uỷ quyền của bạn trong trình duyệt của người dùng. Nếu luồng bắt đầu trên một 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.
2. 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).
3. Dịch vụ của bạn sẽ tạo một mã uỷ quyền và trả về mã đó cho Google. Để làm điều nà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 đính kèm vào yêu cầu.
4. Google sẽ gửi mã uỷ quyền đến điểm cuối trao đổi mã thông báo. Điểm cuối này sẽ xác minh tính xác thực của mã và trả về một mã truy cập và một mã làm mới. Mã truy cập là một mã 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 vào API. Mã làm mới là một mã có thời gian tồn tại lâu dài mà Google có thể lưu trữ và sử dụng để lấy mã truy cập mới khi mã truy cập hết hạn.
5. 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 mà Google gửi sẽ chứa mã truy cập.

Xử lý yêu cầu uỷ quyền

Khi bạn cần thực hiện việc liên kết tài khoản bằng quy trình mã uỷ quyền OAuth 2.0, Google sẽ gửi người dùng đến điểm cuối uỷ quyền của bạn bằng một yêu cầu bao gồm các tham số sau:

Ví dụ: nếu điểm cuối uỷ quyền của bạn có tại https://myservice.example.com/auth, thì 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 uỷ quyền xử lý các yêu cầu đăng nhập, hãy làm theo các bước sau:

1. Xác minh rằng client_id khớp với Mã khách hàng 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 được định cấu hình không chính xác. Nếu bạn hỗ trợ nhiều luồng OAuth 2.0, hãy xác nhận rằng response_type là code.
2. 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ý của dịch vụ.
3. Tạo mã uỷ quyền để Google sử dụng nhằm truy cập vào API của bạn. Mã uỷ quyền có thể là bất kỳ giá trị chuỗi nào, nhưng phải đại diện duy nhất cho người dùng, ứng dụng mà mã thông báo dành cho và thời gian hết hạn của mã, đồng thời không được đoán được. Thông thường, bạn sẽ phát hành mã uỷ quyền có thời hạn sau khoảng 10 phút.
4. Xác nhận rằng URL do tham số redirect_uri chỉ định có dạng sau:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

5. Chuyển hướng trình duyệt của người dùng đến URL do tham số redirect_uri chỉ định. Thê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 thu được:

   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 của dịch vụ chịu trách nhiệm về hai loại giao dịch trao đổi mã thông báo:

• Trao đổi mã uỷ quyền cho mã truy cập và mã làm mới
• Trao đổi mã làm mới cho mã truy cập

Yêu cầu trao đổi mã thông báo bao gồm các tham số sau:

Định cấu hình cách Google gửi thông tin xác thực đến máy chủ của bạn

Tuỳ thuộc vào cách triển khai, máy chủ uỷ quyền của bạn dự kiến sẽ nhận được thông tin xác thực của ứng dụng trong phần nội dung yêu cầu hoặc trong tiêu đề yêu cầu.

Theo mặc định, Google sẽ gửi thông tin xác thực trong phần nội dung yêu cầu. Nếu máy chủ uỷ quyền yêu cầu thông tin xác thực ứng dụng nằm trong tiêu đề yêu cầu, bạn phải định cấu hình chế độ tích hợp Cloud-to-cloud cho phù hợp:

Chuyển đến Developer Console

1. Trong danh sách dự án, hãy nhấp vào Mở bên cạnh dự án mà bạn muốn làm việc.

2. Trong mục Từ đám mây sang đám mây, hãy chọn Phát triển.

3. Nhấp vào Mở bên cạnh công cụ tích hợp.

4. Di chuyển xuống phần Quyền (không bắt buộc) rồi chọn hộp đánh dấu Yêu cầu Google truyền mã ứng dụng khách và mã xác thực qua tiêu đề xác thực cơ bản HTTP.

5. Nhấp vào Lưu để lưu các thay đổi.

Trao đổi mã uỷ 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 uỷ quyền của bạn trả về một mã uỷ quyền ngắn hạn cho Google, Google sẽ gửi một yêu cầu đến điểm cuối trao đổi mã thông báo của bạn để trao đổi mã uỷ quyền lấy mã truy cập và mã làm mới.

Đối với các 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ã uỷ quyền mà bạn đã cấp cho Google trước đó. Sau đây là ví dụ về yêu cầu trao đổi mã uỷ quyền lấy 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 lấy 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 thi các bước sau:

1. 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 uỷ quyền và client_secret khớp với giá trị dự kiến.
2. Xác minh rằng mã uỷ quyền hợp lệ và chưa hết hạn, đồng thời mã ứng dụng được chỉ định trong yêu cầu khớp với mã ứng dụng được liên kết với mã uỷ quyền.
3. Xác nhận rằng URL do tham số redirect_uri chỉ định giống với giá trị được sử dụng trong yêu cầu uỷ quyền ban đầu.
4. Nếu bạn không thể xác minh tất cả các tiêu chí nêu trên, hãy trả về lỗi HTTP 400 Yêu cầu không hợp lệ với nội dung là {"error": "invalid_grant"}.
5. Nếu không, hãy sử dụng mã nhận dạng người dùng trong 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 đại diện riêng cho người dùng và ứng dụng mà mã thông báo dành cho, đồng thời không được đoán được. Đối với mã truy cập, hãy ghi lại cả 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. Mã làm mới không hết hạn.
6. 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, đồng thời ghi lại thời điểm mã 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 của bạn.

Trao đổi mã làm mới cho mã truy cập

Khi mã truy cập hết hạn, Google sẽ gửi một yêu cầu đến điểm cuối trao đổi mã thông báo để trao đổi mã làm mới lấy mã truy cập mới.

Đối với các 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ã làm mới mà bạn đã cấp cho Google trước đó. Sau đây là ví dụ về yêu cầu trao đổi mã làm mới lấy 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ã thông báo 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:

1. Xác minh rằng client_id xác định nguồn gốc yêu cầu là Google và client_secret khớp với giá trị dự kiến.
2. Xác minh rằng mã thông báo làm mới hợp lệ và mã ứng dụng được chỉ định trong yêu cầu khớp với mã ứng dụng được liên kết với mã thông báo làm mới.
3. Nếu bạn không thể xác minh tất cả các tiêu chí nêu trên, hãy trả về lỗi Yêu cầu không hợp lệ HTTP 400 với nội dung là {"error": "invalid_grant"}.
4. Nếu không, hãy sử dụng mã nhận dạng người dùng trong mã thông báo làm mới để tạo 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 đại diện duy nhất cho người dùng và ứng dụng mà mã thông báo dành cho, đồng thời không được đoán được. Đối với mã truy cập, hãy ghi lại cả thời gian hết hạn của mã, thường là một giờ sau khi bạn phát hành mã.
5. Trả về đối tượng JSON sau trong nội dung phản hồi HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Xử lý các yêu cầu thông tin người dùng

Điểm cuối userinfo là một tài nguyên được bảo vệ bằng OAuth 2.0. Tài nguyên này trả về các thông báo xác nhận quyền sở hữu về người dùng được liên kết. Việc triển khai và lưu trữ điểm cuối userinfo là không bắt buộc, ngoại trừ các trường hợp sử dụng sau:

• Đăng nhập vào tài khoản được liên kết bằng tính năng Google One Chạm.
• Gói thuê bao dễ dàng trên Android TV.

Sau khi đã truy xuất thành công mã truy cập từ điểm cuối của mã thông báo, Google sẽ gửi yêu cầu đến điểm cuối userinfo của bạn để truy xuất thông tin hồ sơ cơ bản về người dùng được liên kết.

Ví dụ: nếu điểm cuối userinfo của bạn có sẵn tại https://myservice.example.com/userinfo, một 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:

1. Trích xuất mã truy cập từ tiêu đề Uỷ quyền và trả về thông tin cho người dùng được liên kết với mã truy cập.
2. Nếu mã truy cập không hợp lệ, hãy trả về lỗi HTTP 401 unauthorized (Không được phép sử dụng tiêu đề phản hồi WWW-Authenticate). Dưới đây là ví dụ về phản hồi khi xảy ra lỗi 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 phản hồi 401 Trái phép hoặc bất kỳ lỗi không thành công nào khác được trả về trong quá trình liên kết, thì lỗi này sẽ không khôi phục được, mã thông báo đã truy xuất sẽ bị loại bỏ và người dùng sẽ phải bắt đầu lại quy trình liên kết.

3. Nếu mã truy cập hợp lệ, hãy trả về và phản hồi HTTP 200 kèm theo đối tượng JSON sau trong phần nội dung của HTTPS phản hồi:

   {
   "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 của bạn trả về phản hồi thành công HTTP 200, thì mã thông báo và các thông báo xác nhận quyền sở hữu đã truy xuất sẽ được đăng ký vào Tài khoản Google của người dùng.

   phản hồi của thiết bị đầu cuối userinfo
   sub	Mã nhận dạng duy nhất giúp nhận dạng 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.