Trang này được dịch bởi Cloud Translation API.

Liên kết Tài khoản Google với OAuth

Các tài khoản được liên kết bằng cách sử dụng quy trình ngầm ẩn và mã uỷ quyền OAuth 2.0 tiêu chuẩn ngành. Dịch vụ của bạn phải hỗ trợ điểm cuối ủy quyền và tuân thủ giao thức trao đổi mã thông báo dựa trên OAuth 2.0.

In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.

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.

Choose an OAuth 2.0 flow

Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.

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.

This figure shows the steps for a user to link their Google account
to your authentication system. The first screenshot shows
user-initiated linking from your platform. The second image shows
user sign-in to Google, while the third shows the user consent and
confirmation for linking their Google account with your app. The
final screenshot shows a successfully linked user account in the
Google app. — **Figure 1.** Account linking user sign in to Google and consent screens.

Requirements

You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.

Recommendations

We recommend that you do the following:

Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.
Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.
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.
Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.
Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.
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.
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 and the implicit flow.
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.

Tạo dự án

Cách tạo dự án để sử dụng tính năng liên kết tài khoản:

Go to the Google API Console.
Nhấp vào Tạo dự án .
Nhập tên hoặc chấp nhận đề xuất được tạo.
Xác nhận hoặc chỉnh sửa bất kỳ trường nào còn lại.
Nhấp vào Tạo .

Để xem ID dự án của bạn:

Go to the Google API Console.
Tìm dự án của bạn trong bảng trên trang đích. ID dự án xuất hiện trong cột ID .

Định cấu hình Màn hình xin phép bằng Oauth

Quy trình Liên kết tài khoản Google bao gồm một màn hình đồng ý cho người dùng biết ứng dụng yêu cầu quyền truy cập vào dữ liệu của họ, loại dữ liệu họ đang yêu cầu và các điều khoản áp dụng. Bạn sẽ phải định cấu hình màn hình xin phép bằng OAuth trước khi tạo mã ứng dụng khách Google API.

Mở trang Màn hình xin phép bằng OAuth của bảng điều khiển API của Google.
Nếu thấy lời nhắc, hãy chọn dự án bạn vừa tạo.
Trên trang "OAuth đồng ý" điền, hãy điền vào biểu mẫu và nhấp vào nút “Lưu”.

Tên ứng dụng: Tên của ứng dụng yêu cầu sự đồng ý. Tên này phải phản ánh chính xác ứng dụng của bạn và nhất quán với tên ứng dụng mà người dùng thấy ở nơi khác. Tên ứng dụng sẽ được hiển thị trên màn hình đồng ý Liên kết tài khoản.

Biểu trưng của ứng dụng: Hình ảnh trên màn hình đồng ý sẽ giúp người dùng nhận ra ứng dụng của bạn. Biểu trưng này sẽ hiển thị trên màn hình đồng ý liên kết Tài khoản và trong phần cài đặt tài khoản

Email hỗ trợ: Cho phép người dùng liên hệ với bạn khi có thắc mắc về sự đồng ý của họ.

Phạm vi cho API Google: Phạm vi cho phép ứng dụng của bạn truy cập vào dữ liệu Google riêng tư của người dùng. Đối với trường hợp sử dụng Liên kết Tài khoản Google, phạm vi mặc định (email, hồ sơ, openid) là đủ, bạn không cần thêm bất kỳ phạm vi nhạy cảm nào. Nhìn chung, phương pháp hay nhất là yêu cầu mở rộng phạm vi tại thời điểm yêu cầu quyền truy cập, thay vì lên trước. Tìm hiểu thêm.

Miền được cấp phép: Để bảo vệ bạn và người dùng, Google chỉ cho phép các ứng dụng xác thực bằng OAuth sử dụng Miền được ủy quyền. Ứng dụng của bạn\39; các đường liên kết phải được lưu trữ trên Miền được cấp phép. Tìm hiểu thêm.

Đường liên kết đến trang chủ ứng dụng: Trang chủ cho ứng dụng của bạn. Phải được lưu trữ trên Miền được cấp phép.

Đường liên kết đến Chính sách quyền riêng tư của ứng dụng: Hiển thị trên màn hình xin phép việc Liên kết tài khoản Google. Phải được lưu trữ trên Miền được cấp phép.

Đường liên kết đến Điều khoản dịch vụ của ứng dụng (Không bắt buộc): Phải được lưu trữ trên một Miền được cấp phép.

Hình 1 Màn hình xin phép liên kết tài khoản Google đối với một ứng dụng giả định, Tuningy
Kiểm tra "Trạng thái xác minh"; nếu đơn đăng ký của bạn cần xác minh, hãy nhấp vào nút "Gửi để xác minh" gửi đơn đăng ký của bạn để xác minh. Hãy tham khảo các yêu cầu về việc xác minh OAuth để biết thông tin chi tiết.

Triển khai máy chủ OAuth

Một OAuth 2.0 máy chủ thực hiện các dòng mã uỷ quyền bao gồm hai thiết bị đầu cuối, mà dịch vụ của bạn làm sẵn bằng HTTPS. Điểm cuối đầu tiên là điểm cuối ủy quyền, có nhiệm vụ tìm kiếm hoặc lấy sự đồng ý từ người dùng để truy cập dữ liệu. Đ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 của bạn 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 sử dụng để lấy các chuỗi được mã hóa, được gọi là mã thông báo, cho phép người dùng truy cập 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 dịch vụ của bạn, 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 mặt họ.

Một phiên quy trình mã ủy quyền OAuth 2.0 do Google bắt đầu có quy trình sau:

Google 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ỉ thoại cho một Hành động, thì Google sẽ chuyển việc 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 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 ra một mã uỷ quyền và trả nó về 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ã ủy quyền được đính kèm với yêu cầu.
Google gửi mã ủy quyền cho thiết bị đầu cuối trao đổi thẻ của bạn, mà xác minh tính xác thực của mã và trả về một access token và refresh token. Mã thông báo truy cập là mã thông báo tồn tại trong thời gian ngắ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ã thông báo làm mới là mã thông báo tồn tại lâu dài mà Google có thể lưu trữ và sử dụng để có được mã thông báo truy cập mới khi chúng 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ã thông báo truy cập.

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

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

Tham số điểm cuối ủy quyền
`client_id`	ID khách hàng mà bạn đã chỉ định cho Google.
`redirect_uri`	URL mà bạn gửi phản hồi cho yêu cầu này.
`state`	Giá trị sổ sách kế toán được chuyển lại cho Google không thay đổi trong URI chuyển hướng.
`scope`	Tùy chọn: Một bộ không gian được phân định các chuỗi phạm vi mà xác định dữ liệu của Google đang yêu cầu ủy quyền cho.
`response_type`	Loại giá trị sẽ trả về trong phản hồi. Đối với quyền của OAuth 2.0 dòng mã, kiểu phản ứng luôn là `code` .
`user_locale`	Cài đặt ngôn ngữ tài khoản Google trong RFC5646 định dạng, được sử dụng để bản địa hoá nội dung của bạn trong ngôn ngữ ưa thích của người dùng.

Ví dụ, nếu thiết bị đầu cuối cho phép bạn có sẵn tại https://myservice.example.com/auth , một 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&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 các client_id phù hợp với ID ứng dụng bạn đã gán cho Google, và rằng redirect_uri phù hợp với URL chuyển hướng cung cấp bởi Google 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 OAuth dòng 2.0, cũng xác nhận rằng response_type là code .
Kiểm tra xem người dùng đã đăng nhập vào dịch vụ của bạn 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ý dịch vụ của bạn.
Tạo mã ủy quyền để Google sử dụng để truy cập API của bạn. Mã ủy quyền có thể là bất kỳ giá trị chuỗi nào, nhưng nó phải đại diện duy nhất cho người dùng, khách hàng mà mã thông báo dành cho và thời gian hết hạn của mã, và nó phải không thể đoán được. Bạn thường cấp mã ủy quyền sẽ hết hạn sau khoảng 10 phút.

Xác nhận rằng URL được chỉ định bởi các redirect_uri tham số có dạng 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 chỉ định bởi các redirect_uri tham số. Bao gồm mã cho phép bạn vừa tạo ra và bản gốc, giá trị trạng thái chưa sửa đổi khi bạn chuyển hướng bằng cách thêm các code và state tham số. Sau đây là một ví dụ về URL kết quả:
```
https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
```

Xử lý các 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ụ của bạn chịu trách nhiệm cho hai loại trao đổi mã thông báo:

Trao đổi mã ủy quyền để lấy mã thông báo truy cập và mã làm mới
Trao đổi mã thông báo làm mới để lấy 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`	Một 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 mã nhận dạng duy nhất của Google.
`client_secret`	Một 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 được trao đổi. Nó là một trong hai `authorization_code` hoặc `refresh_token` .
`code`	Khi `grant_type=authorization_code` , thông số này là mã Google nhận được từ một trong hai đăng nhập của bạn hoặc thẻ trao đổi thiết bị đầu cuối.
`redirect_uri`	Khi `grant_type=authorization_code` , thông số này là URL được sử dụng trong yêu cầu uỷ quyền ban đầu.
`refresh_token`	Khi `grant_type=refresh_token` , thông số này là làm mới thẻ Google nhận được từ thiết bị đầu cuối trao đổi thẻ của bạn.

Trao đổi mã ủy quyền để lấy mã thông báo 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ả lại 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 để trao đổi mã ủy quyền lấy mã thông báo 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 trước đó bạn cấp cho Google. Sau đây là ví dụ về yêu cầu trao đổi mã ủy quyền lấy mã thông báo truy cập và mã thông báo 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ã ủy quyền cho một access token và làm mới thẻ, thẻ trao đổi thiết bị đầu cuối trä l của bạn để POST yêu cầu bằng cách thực hiện các bước sau:

Xác minh rằng các client_id xác định các yêu cầu nguồn gốc như một nguồn gốc được ủy quyền, và rằng client_secret phù hợp với giá trị kỳ vọng.
Xác minh rằng mã ủy quyền hợp lệ và chưa hết hạn và ID khách hàng được chỉ định trong yêu cầu khớp với ID khách hàng được liên kết với mã ủy quyền.
Xác nhận rằng URL được chỉ định bởi các redirect_uri thông số giống hệt với giá trị sử 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, trả lại một Bad Request lỗi HTTP 400 với {"error": "invalid_grant"} là cơ quan.
Nếu không, hãy sử dụng ID người dùng từ mã ủy quyền để tạo mã thông báo làm mới và mã thông báo truy cập. Những mã thông báo này có thể là bất kỳ giá trị chuỗi nào, nhưng chúng phải đại diện duy nhất cho người dùng và khách hàng mà mã thông báo dành cho nó và chúng không được đoán. Đối với mã thông báo truy cập, cũng 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. Làm mới mã thông báo không hết hạn.

Trả lại đối tượng JSON sau trong cơ thể của phản ứng HTTPS:

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

Google lưu trữ mã thông báo truy cập và mã làm mới cho người dùng và ghi lại thời gian hết hạn của mã thông báo truy cập. Khi mã truy cập hết hạn, Google sử dụng mã làm mới để nhận 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ã thông báo làm mới để lấy mã thông báo truy cập

Khi mã thông báo 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 để đổi mã làm mới lấy 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 được refresh_token , và giá trị của refresh_token là giá trị của thẻ refresh trước đó bạn cấp cho Google. Sau đây là ví dụ về yêu cầu trao đổi mã thông báo làm mới lấy mã thông báo 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ột refresh mã thông báo cho một thẻ truy cập, thẻ trao đổi thiết bị đầu cuối trä l của bạn để POST yêu cầu bằng cách thực hiện các bước sau:

Xác minh rằng các client_id xác định các yêu cầu nguồn gốc như Google, và rằng client_secret phù hợp với giá trị kỳ vọng.
Xác minh rằng mã thông báo làm mới hợp lệ và ID ứng dụng khách được chỉ định trong yêu cầu khớp với ID ứng dụng khách được 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, trả lại một Bad Request lỗi HTTP 400 với {"error": "invalid_grant"} là cơ quan.
Nếu không, hãy sử dụng ID người dùng từ mã 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 chúng phải đại diện duy nhất cho người dùng và khách hàng mà mã thông báo đó dành cho và chúng không được đoán. Đối với mã thông báo truy cập, cũng 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ả lại đố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ý các yêu cầu thông tin sử dụng

Các thiết bị đầu cuối UserInfo là một nguồn tài nguyên được bảo vệ OAuth 2.0 rằng tuyên bố trở 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à tùy chọn, ngoại trừ các trường hợp sử dụng sau:

Liên kết Tài khoản đăng nhập với Google Một Tap.
Thuê bao không ma sát trên AndroidTV.

Sau khi mã thông báo truy cập đã được truy xuất thành công từ điểm cuối mã thông báo của bạn, 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.

tiêu đề yêu cầu điểm cuối userinfo
`Authorization header`	Mã thông báo truy cập của loại Bearer.

Ví dụ, nếu thiết bị đầu 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ể trông như sau:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Để điểm cuối userinfo của bạn có thể xử lý các yêu cầu, hãy làm theo các bước sau:

Trích xuất mã thông báo truy cập từ tiêu đề Ủy quyền và trả lại thông tin cho người dùng được liên kết với mã thông báo truy cập.
Nếu mã thông báo truy cập không hợp lệ, trả về một lỗi HTTP 401 Unauthorized với việc sử dụng WWW-Authenticate đáp ứng Header. Dưới đây là một ví dụ về một phản ứng lỗi UserInfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
Nếu một 401 Unauthorized, hoặc bất kỳ phản ứng lỗi không thành công khác được trả về trong quá trình liên kết, các lỗi sẽ không thể phục hồi được, token truy xuất sẽ bị loại bỏ và người dùng sẽ có để bắt đầu lại quá trình liên kết.

Nếu mã thông báo truy cập có giá trị, lợi nhuận và HTTP 200 phản ứng với các đối tượng JSON sau trong cơ thể của HTTPS phản ứng:

{
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}

Nếu UserInfo bạn endpoint lợi nhuận một thành công phản ứng HTTP 200, lấy token và tuyên bố được đăng ký so với của người dùng Google tài khoản.

phản hồi điểm cuối userinfo
`sub`	Một ID 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`	Tùy chọn: First name của người dùng.
`family_name`	Tùy chọn: Last name của người dùng.
`name`	Tùy chọn: Họ và tên của người dùng.
`picture`	Tùy chọn: Profile picture của người dùng.

Xác thực quá trình triển khai

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

Click Configuration to open the OAuth 2.0 Configuration window.
In the OAuth flow field, select Client-side.
In the OAuth Endpoints field, select Custom.
Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

Click the Sign-in with Google button.
Choose the account you'd like to link.
Enter the service ID.
Optionally enter one or more scopes that you will request access for.
Click Start Demo.
When prompted, confirm that you may consent and deny the linking request.
Confirm that you are redirected to your platform.