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ó 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 yêu cầu thực hiện nhận được một ý định 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 chế độ tích hợp Cloud-to-cloud.

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

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

• The token exchange endpoint, which is responsible for two types of exchanges:

  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
2. You must have a Google authorization statement such as "By signing in, you are authorizing Google to control your devices." See the Google Device Control Authorization section of the Google Home Developer Policies.
3. You must open the Web OAuth linking page and ensure users have a clear method for signing in to their Google Account, such as fields for their username and password. Don't use the Google Sign-In (GSI) method that enables users to link without being taken to the Web OAuth Linking page. It is a violation of Google policy.
4. You must include at least one of the following items in the OAuth linking page to indicate the integration to which the user is linking:
   • Company logo
   • Company name
   • Integration name
   • App icon

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Clear sign-in process. Ensure that users have a clear method for signing in to their Google Account, such as fields for their username and password or Sign in with Google.

6. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

7. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking.

8. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

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

Việc triển khai máy chủ OAuth 2.0 của quy trình mã uỷ quyền bao gồm 2 đ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 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 vào dữ liệu. Điểm cuối uỷ quyền trình bày một 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. Điểm cuối này được dùng để lấy các chuỗi được 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 để được người dùng của bạn cho phép gọi các API này thay cho họ.

Một phiên quy trình mã uỷ quyền OAuth 2.0 do Google khởi tạo có quy trình 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 quy trình bắt đầu trên một thiết bị chỉ có giọng nói cho một Thao tác, thì Google sẽ chuyển việc 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 tạo một mã uỷ quyền và trả mã đó về cho Google. Để làm như vậy, hãy chuyển hướng trình duyệt của người dùng trở lại Google với mã uỷ quyền được đính kèm vào yêu cầu.
4. Google gửi mã uỷ quyền đến điểm cuối trao đổi mã thông báo của bạn. Điểm cuối này 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 đăng nhập để truy cập vào các API. Mã làm mới là một mã thông báo có thời hạn sử dụng 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 được gửi từ Google đều chứa mã truy cập.

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

Khi bạn cần thực hiện quy trình 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ể trô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

Để đ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ã ứ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 cho các ứng dụng khách không mong muốn hoặc được định cấu hình sai. Nếu bạn hỗ trợ nhiều luồng OAuth 2.0, hãy xác nhận rằng response_type cũng là code.
2. Kiểm tra xem người dùng đã đăng nhập vào dịch vụ của bạn hay chưa. 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 phép đoán được. Bạn thường cấp mã uỷ quyền hết 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 như 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 mà bạn vừa tạo và giá trị trạng thái ban đầu, chưa được sửa đổi khi bạn chuyển hướng bằng cách nối 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 của dịch vụ chịu trách nhiệm về 2 loại trao đổi mã thông báo:

• Trao đổi mã uỷ quyền để lấy mã truy cập và mã làm mới
• Đổi mã làm mới thành 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 đăng nhập của ứng dụng trong 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 đăng nhập trong phần nội dung yêu cầu. Nếu máy chủ uỷ quyền của bạn yêu cầu thông tin đăng nhập của ứng dụng nằm trong tiêu đề yêu cầu, thì 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 Cloud-to-Cloud, hãy chọn Develop (Phát triển).

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

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 Cho phép Google truyền Mã ứng dụng khách và khoá bí mật thông 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 để lấy 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 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ã 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 của bạn 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:

1. Xác minh rằng client_id xác định nguồn gốc của 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 để đảm bảo 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 hệt với giá trị được 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 Bad Request với {"error": "invalid_grant"} làm nội dung.
5. Nếu không, hãy sử dụng mã nhận dạng người dùng từ mã uỷ quyền để tạo mã làm mới và mã 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 biệ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 thời gian hết hạn của mã thông báo. Thời gian này 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 đây trong 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 gian hết hạn của mã truy cập. 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.

Đổi mã làm mới thành 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 của bạn để trao đổi mã làm mới lấy một mã 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ã 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ã làm mới lấy mã truy cập, điểm cuối trao đổi mã thông báo của bạn 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:

1. 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.
2. Xác minh rằng mã làm mới 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 được liên kết với mã 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 HTTP 400 Bad Request với {"error": "invalid_grant"} làm nội dung.
4. Nếu không, hãy sử dụng mã nhận dạng người dù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à bất kỳ giá trị chuỗi nào, nhưng phải đại diện riêng biệ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 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.
5. Trả về đối tượng JSON sau đây trong nội dung phản hồi 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.

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:

1. Extract access token from the Authorization header and return information for the user associated with the access token.
2. 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.

3. 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.