Tính năng Liên kết Tài khoản Google cho phép chủ Tài khoản Google kết nối nhanh chóng, mượt mà và an toàn với các dịch vụ và chia sẻ dữ liệu với Google.
Tính năng Đăng nhập bằng tài khoản được liên kết bật tính năng Đăng nhập bằng một lần chạm bằng Google cho những người dùng đã liên kết Tài khoản Google của họ với dịch vụ của bạn. Điều này giúp cải thiện trải nghiệm cho người dùng vì họ có thể đăng nhập chỉ bằng một thao tác nhấp mà không cần nhập lại tên người dùng và mật khẩu. Điều này cũng làm giảm cơ hội người dùng tạo tài khoản trùng lặp trên dịch vụ của bạn.
Yêu cầu
Để triển khai Đăng nhập vào tài khoản được liên kết, bạn phải đáp ứng các yêu cầu sau:
- Bạn đã triển khai Liên kết OAuth với Tài khoản Google để hỗ trợ quy trình mã ủy quyền OAuth 2.0. Việc triển khai OAuth phải bao gồm các điểm cuối sau đây:
- điểm cuối ủy quyền để xử lý các yêu cầu ủy quyền.
- điểm cuối mã thông báo để xử lý yêu cầu truy cập và làm mới mã thông báo.
- điểm cuối của thông tin người dùng để truy xuất thông tin tài khoản cơ bản về người dùng đã liên kết. Thông tin này sẽ hiển thị cho người dùng trong quá trình Đăng nhập vào tài khoản được liên kết.
- Bạn có một ứng dụng Android.
Cách hoạt động
Điều kiện tiên quyết : Người dùng đã liên kết Tài khoản Google của họ với tài khoản của họ trên dịch vụ của bạn trước đây.
- Bạn có thể chọn hiển thị các tài khoản được liên kết trong quy trình Đăng nhập bằng một lần chạm.
- Người dùng sẽ thấy lời nhắc Đăng nhập bằng một lần chạm có tùy chọn đăng nhập vào dịch vụ của bạn bằng tài khoản được liên kết của họ.
- Nếu người dùng chọn tiếp tục dùng tài khoản được liên kết, Google sẽ gửi yêu cầu đến điểm cuối mã thông báo của bạn để lưu mã ủy quyền. Yêu cầu này chứa mã truy cập của người dùng do dịch vụ của bạn cấp và một mã ủy quyền của Google.
- Bạn đổi mã ủy quyền của Google để có một mã Google ID chứa thông tin về Tài khoản Google của người dùng.
- Ứng dụng của bạn cũng nhận được mã thông báo nhận dạng khi luồng hoàn tất và bạn so khớp mã này với mã nhận dạng người dùng trong mã thông báo nhận dạng mà máy chủ đã nhận để đăng nhập người dùng vào ứng dụng của bạn.
Triển khai đăng nhập bằng tài khoản được liên kết trong ứng dụng Android
Để hỗ trợ Đăng nhập vào tài khoản được liên kết trên ứng dụng Android, hãy làm theo hướng dẫn trong Hướng dẫn triển khai Android.
Xử lý các yêu cầu mã uỷ quyền từ Google
Google gửi yêu cầu POST đến điểm cuối mã thông báo của bạn để lưu mã ủy quyền mà bạn trao đổi cho mã thông báo mã của người dùng. Yêu cầu này chứa mã truy cập của người dùng và mã ủy quyền OAuth2 của Google.
Trước khi lưu mã ủy quyền, bạn phải xác minh mã truy cập do bạn cấp cho Google (do client_id xác định).
Yêu cầu HTTP
Yêu cầu mẫu
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN
Điểm cuối trao đổi mã thông báo của bạn phải có thể xử lý các thông số yêu cầu sau:
| Thông số điểm cuối mã thông báo | |
|---|---|
code |
Bắt buộc Mã ủy quyền Google OAuth2 |
client_id |
Bắt buộc Mã ứng dụng mà bạn đã cấp cho Google |
client_secret |
Bắt buộc Mật khẩu ứng dụng mà bạn đã cấp cho Google |
access_token |
Bắt buộc Mã thông báo truy cập mà bạn cấp cho Google. Bạn sẽ dùng tùy chọn này để biết bối cảnh của người dùng |
grant_type |
Giá trị Bắt buộc PHẢI được đặt thành urn:ietf:params:oauth:grant-type:reciprocal |
Điểm cuối trao đổi mã thông báo của bạn sẽ phản hồi yêu cầu POST bằng cách làm như sau:
- Xác minh rằng
access_tokenđã đượcclient_idcấp cho Google. - Phản hồi bằng phản hồi HTTP 200 (OK) nếu yêu cầu hợp lệ và mã xác thực được đổi thành công cho một mã thông báo Google ID hoặc mã lỗi HTTP nếu yêu cầu không hợp lệ.
Phản hồi HTTP
Thành công
Trả về mã trạng thái HTTP 200 OK
Ví dụ về phản hồi thành công
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}
Lỗi
Trong trường hợp có một yêu cầu HTTP không hợp lệ, hãy phản hồi bằng một trong các mã lỗi HTTP sau:
| Mã trạng thái HTTP | Nội dung | Mô tả |
|---|---|---|
| 400 | {"error": "invalid_request"} |
Yêu cầu thiếu một thông số nên máy chủ không thể tiếp tục yêu cầu. Kết quả này cũng có thể được trả về nếu yêu cầu bao gồm thông số không được hỗ trợ hoặc lặp lại thông số |
| 401 | {"error": "invalid_request"} |
Xác thực máy khách không thành công, chẳng hạn như nếu yêu cầu chứa mã ứng dụng hoặc mã thông báo bí mật không hợp lệ |
| 401 | {"error": "invalid_token"}
Bao gồm "WWW-Authentication: Bearer" auth Challenge trong tiêu đề phản hồi |
Mã truy cập của đối tác không hợp lệ. |
| 403 | {"error": "insufficient_permission"}
Bao gồm "WWW-Authentication: Bearer" auth Challenge trong tiêu đề phản hồi |
Mã truy cập của đối tác không chứa(các) phạm vi cần thiết để thực hiện OAuth bổ sung |
| 500 | {"error": "internal_error"} |
Lỗi máy chủ |
Nội dung phản hồi lỗi phải chứa các trường sau :
| Các trường phản hồi lỗi | |
|---|---|
error |
Bắt buộc chuỗi lỗi |
error_description |
Mô tả lỗi có thể đọc được |
error_uri |
URI cung cấp thêm chi tiết về lỗi |
Phản hồi lỗi 400 mẫu
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request",
"error_description": "Request was missing the 'access_token' parameter."
}
Mã ủy quyền trao đổi cho mã thông báo mã nhận dạng
Bạn sẽ cần trao đổi mã ủy quyền mà bạn đã nhận được để có một mã Google ID chứa mã thông tin về Tài khoản Google của người dùng.
Để đổi mã uỷ quyền cho mã Google ID, hãy gọi điểm cuối https://oauth2.googleapis.com/token và đặt các thông số sau:
| Trường yêu cầu | |
|---|---|
client_id |
Bắt buộc Mã máy khách lấy từ trang Thông tin xác thực của Bảng điều khiển API. Thông thường, đó sẽ là thông tin đăng nhập có tên là Thao tác mới trên ứng dụng Google |
client_secret |
Bắt buộc Mật khẩu ứng dụng khách lấy từ trang Thông tin xác thực của Bảng điều khiển API |
code |
Bắt buộc Mã ủy quyền được gửi trong yêu cầu ban đầu |
grant_type |
Bắt buộc Như đã xác định trong quy cách OAuth 2.0, bạn phải đặt giá trị của trường này là authorization_code. |
Yêu cầu mẫu
POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET
Google phản hồi yêu cầu này bằng cách trả về một đối tượng JSON chứa mã truy cập ngắn hạn và mã làm mới.
Phản hồi chứa các trường sau:
| Trường phản hồi | |
|---|---|
access_token |
Mã truy cập do Google cấp mà ứng dụng của bạn gửi để cho phép yêu cầu API Google |
id_token |
Mã nhận dạng này chứa thông tin Tài khoản Google của người dùng. Phần Xác thực phản hồi chứa thông tin chi tiết về cách giải mã và xác thực phản hồi mã thông báo ID |
expires_in |
Thời gian còn lại của mã thông báo truy cập tính bằng giây |
refresh_token |
Mã thông báo mà bạn có thể sử dụng để lấy mã truy cập mới. Mã làm mới sẽ có hiệu lực cho đến khi người dùng thu hồi quyền truy cập |
scope |
Giá trị của trường này luôn được đặt thành Openid cho trường hợp sử dụng Đăng nhập vào tài khoản được liên kết |
token_type |
Loại mã thông báo được trả về. Hiện tại, giá trị của trường này luôn được đặt thành Bearer |
Phản hồi mẫu
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
{
"access_token": "Google-access-token",
"id_token": "Google-ID-token",
"expires_in": 3599,
"token_type": "Bearer",
"scope": "openid",
"refresh_token": "Google-refresh-token"
}
POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret
Xác thực phản hồi mã thông báo mã nhận dạng
Xác thực và giải mã khẳng định JWT
Bạn có thể xác thực và giải mã xác nhận JWT bằng cách sử dụng thư viện giải mã JWT cho ngôn ngữ của bạn . Sử dụng khóa công khai của Google, có sẵn ở định dạng JWK hoặc PEM , để xác minh chữ ký của mã thông báo.
Khi được giải mã, xác nhận JWT trông giống như ví dụ sau:
{
"sub": "1234567890", // The unique ID of the user's Google Account
"iss": "https://accounts.google.com", // The assertion's issuer
"aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
"iat": 233366400, // Unix timestamp of the assertion's creation time
"exp": 233370000, // Unix timestamp of the assertion's expiration time
"name": "Jan Jansen",
"given_name": "Jan",
"family_name": "Jansen",
"email": "jan@gmail.com", // If present, the user's email address
"email_verified": true, // true, if Google has verified the email address
"hd": "example.com", // If present, the host domain of the user's GSuite email address
// If present, a URL to user's profile picture
"picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
"locale": "en_US" // User's locale, from browser or phone settings
}
Ngoài xác minh chữ ký của mã thông báo, xác minh rằng tổ chức phát hành của sự khẳng định ( iss trường) là https://accounts.google.com , mà khán giả ( aud trường) là ID của khách hàng được phân công của mình, và rằng các dấu hiệu chưa hết hạn ( exp cánh đồng).
Sử dụng các trường email , email_verified và hd bạn có thể xác định xem Google có lưu trữ và có thẩm quyền cho một địa chỉ email hay không. Trong trường hợp Google có thẩm quyền, người dùng hiện được coi là chủ sở hữu tài khoản hợp pháp và bạn có thể bỏ qua mật khẩu hoặc các phương pháp thử thách khác. Nếu không, các phương pháp này có thể được sử dụng để xác minh tài khoản trước khi liên kết.
Các trường hợp mà Google có thẩm quyền:
-
emailcó hậu tố@gmail.com, đây là tài khoản Gmail. -
email_verifiedlà true vàhdđược đặt, đây là tài khoản G Suite.
Người dùng có thể đăng ký Tài khoản Google mà không cần sử dụng Gmail hoặc G Suite. Khi email không chứa hậu tố @gmail.com và không có hd Google không có thẩm quyền và bạn nên sử dụng mật khẩu hoặc các phương pháp thử thách khác để xác minh người dùng. email_verfied cũng có thể đúng vì ban đầu Google đã xác minh người dùng khi tài khoản Google được tạo, tuy nhiên quyền sở hữu tài khoản email của bên thứ ba có thể đã thay đổi.