Liên kết hợp lý với OAuth và Đăng nhập bằng Google

Tổng quat

Đăng nhập bằng Google dựa trên OAuth Liên kết được tổ chức hợp lý thêm Đăng nhập bằng Google vào đầu liên kết OAuth . Điều này cung cấp trải nghiệm liên kết liền mạch cho người dùng Google và nó cũng cho phép liên kết tài khoản cho những người dùng đã đăng ký dịch vụ của bạn với danh tính không phải của Google.

Để thực hiện liên kết tài khoản với OAuth và Đăng nhập bằng Google, hãy làm theo các bước chung sau:

  1. Trước tiên, hãy yêu cầu người dùng đồng ý để truy cập hồ sơ trên Google của họ.
  2. Sử dụng thông tin trong hồ sơ của họ để kiểm tra xem tài khoản người dùng có tồn tại hay không.
  3. Đối với người dùng hiện tại, hãy liên kết các tài khoản.
  4. Nếu bạn không thể tìm thấy kết quả phù hợp cho người dùng Google trong hệ thống xác thực của mình, hãy xác thực mã thông báo ID nhận được từ Google. Sau đó, bạn có thể tạo người dùng dựa trên thông tin hồ sơ có trong mã thông báo ID.

Hình 3 . Liên kết tài khoản trên điện thoại của người dùng với Liên kết hợp lý

Các tài khoản được liên kết bằng cách sử dụng các luồng mã ủy quyềnngầm định OAuth 2.0 tiêu chuẩn ngành. Dịch vụ của bạn phải hỗ trợ ủy quyền tuân thủ OAuth 2.0 và các điểm cuối trao đổi mã thông báo . Ngoài ra, điểm cuối trao đổi mã thông báo của bạn phải hỗ trợ xác nhận thông báo web JSON (JWT) và triển khai check , createget ý định.

Nhận bí mật và ID ứng dụng khách API Google của bạn

Bạn sẽ cần lấy Bí mật và ID ứng dụng khách API của mình bằng cách sử dụng dự án bạn đã tạo trong khi hoàn thành các bước Liên kết OAuth . Để làm như vậy, hãy hoàn thành các bước sau:

  1. Mở trang Thông tin đăng nhập của bảng điều khiển API Google .
  2. Tạo hoặc chọn một dự án API của Google.

    Nếu dự án của bạn không có ID ứng dụng khách cho Loại ứng dụng web, hãy nhấp vào Tạo thông tin xác thực> ID ứng dụng khách OAuth để tạo. Đảm bảo bao gồm tên miền của trang web của bạn trong hộp Nguồn gốc JavaScript được ủy quyền . Khi bạn thực hiện kiểm tra hoặc phát triển cục bộ, bạn phải thêm cả http://localhosthttp://localhost:<port_number> vào trường Nguồn gốc JavaScript được ủy quyền .

Triển khai máy chủ OAuth của bạn

Kiểm tra tài khoản người dùng hiện có

Sau khi người dùng đồng ý truy cập hồ sơ trên Google của họ, Google sẽ gửi một yêu cầu chứa xác nhận có chữ ký về danh tính của người dùng Google. Xác nhận chứa thông tin bao gồm ID tài khoản Google, tên và địa chỉ email của người dùng. Điểm cuối trao đổi mã thông báo được định cấu hình cho dự án của bạn xử lý yêu cầu đó.

Nếu tài khoản Google tương ứng đã có trong hệ thống xác thực của bạn, thì điểm cuối trao đổi mã thông báo của bạn sẽ phản hồi bằng account_found=true . Nếu tài khoản Google không khớp với người dùng hiện tại, điểm cuối trao đổi mã thông báo của bạn sẽ trả về lỗi HTTP 404 Not Found với account_found=false .

Yêu cầu có dạng sau:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=check&assertion=JWT&scope=SCOPES

Đ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ố sau:

Thông số điểm cuối mã thông báo
intent Đối với những yêu cầu này, giá trị của tham số này được check .
grant_type Loại mã thông báo được trao đổi. Đối với những yêu cầu này, tham số này có giá trị urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion Mã thông báo web JSON (JWT) cung cấp xác nhận có chữ ký về danh tính của người dùng Google. JWT chứa thông tin bao gồm ID tài khoản Google, tên và địa chỉ email của người dùng.

Khi điểm cuối trao đổi mã thông báo của bạn nhận được yêu cầu check , nó cần xác thực và giải mã xác nhận JWT.

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_verifiedhd 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:

  • email có hậu tố @gmail.com , đây là tài khoản Gmail.
  • email_verified là 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.

Kiểm tra xem tài khoản Google đã có trong hệ thống xác thực của bạn chưa

Kiểm tra xem một trong các điều kiện sau có đúng không:

  • ID tài khoản Google, được tìm thấy trong trường sub của xác nhận, nằm trong cơ sở dữ liệu người dùng của bạn.
  • Địa chỉ email trong xác nhận khớp với một người dùng trong cơ sở dữ liệu người dùng của bạn.

Nếu một trong hai điều kiện là đúng, người dùng đã đăng ký. Trong trường hợp đó, hãy trả lại một phản hồi như sau:

HTTP/1.1 200 Success
Content-Type: application/json;charset=UTF-8

{
  "account_found":"true",
}

Sau đó, Google hiển thị hộp thoại đồng ý liên kết cho người dùng và yêu cầu đồng ý cho các phạm vi mong muốn để tiếp tục liên kết. Sau khi Google nhận được sự đồng ý của người dùng, Google sẽ gửi yêu cầu get đến điểm cuối mã thông báo của bạn để tiếp tục liên kết.

Nếu cả ID tài khoản Google và địa chỉ email được chỉ định trong xác nhận đều khớp với người dùng trong cơ sở dữ liệu của bạn, thì người dùng đó chưa đăng ký. Trong trường hợp này, điểm cuối trao đổi mã thông báo của bạn cần trả lời bằng lỗi HTTP 404 chỉ định "account_found": "false" , như trong ví dụ sau:

HTTP/1.1 404 Not found
Content-Type: application/json;charset=UTF-8

{
  "account_found":"false",
}
Khi Google nhận được phản hồi lỗi 404 với lỗi "account_found": "false" , Google sẽ hiển thị hộp thoại cho người dùng để yêu cầu đồng ý tạo tài khoản mới và truy cập vào phạm vi mong muốn. Sau khi Google nhận được sự đồng ý của người dùng, Google gọi điểm cuối trao đổi mã thông báo của bạn với giá trị của thông số intent được đặt để create và bao gồm mã thông báo ID chứa thông tin hồ sơ của người dùng với yêu cầu.

Xử lý liên kết tự động

Sau khi người dùng đồng ý truy cập hồ sơ trên Google của họ, Google sẽ gửi một yêu cầu chứa xác nhận có chữ ký về danh tính của người dùng Google. Xác nhận chứa thông tin bao gồm ID tài khoản Google, tên và địa chỉ email của người dùng. Điểm cuối trao đổi mã thông báo được định cấu hình cho dự án của bạn xử lý yêu cầu đó.

Nếu Tài khoản Google tương ứng đã có trong hệ thống xác thực của bạn, thì điểm cuối trao đổi mã thông báo của bạn sẽ trả lại mã thông báo cho người dùng. Nếu Tài khoản Google không khớp với người dùng hiện tại, thì điểm cuối trao đổi mã thông báo của bạn sẽ trả về lỗi linking_errorlogin_hint tùy chọn.

Yêu cầu có dạng sau:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&intent=get&assertion=JWT&scope=SCOPES

Đ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ố sau:

Thông số điểm cuối mã thông báo
intent Đối với những yêu cầu này, giá trị của tham số này là get .
grant_type Loại mã thông báo được trao đổi. Đối với những yêu cầu này, tham số này có giá trị urn:ietf:params:oauth:grant-type:jwt-bearer .
assertion Mã thông báo web JSON (JWT) cung cấp xác nhận có chữ ký về danh tính của người dùng Google. JWT chứa thông tin bao gồm ID tài khoản Google, tên và địa chỉ email của người dùng.
scope Tùy chọn: Bất kỳ phạm vi nào mà bạn đã định cấu hình Google để yêu cầu từ người dùng.

Khi điểm cuối trao đổi mã thông báo của bạn nhận được yêu cầu liên kết, nó cần xác thực và giải mã xác nhận JWT.

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_verifiedhd 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:

  • email có hậu tố @gmail.com , đây là tài khoản Gmail.
  • email_verified là 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.

Kiểm tra xem tài khoản Google đã có trong hệ thống xác thực của bạn chưa

Kiểm tra xem một trong các điều kiện sau có đúng không:

  • ID tài khoản Google, được tìm thấy trong trường sub của xác nhận, nằm trong cơ sở dữ liệu người dùng của bạn.
  • Địa chỉ email trong xác nhận khớp với một người dùng trong cơ sở dữ liệu người dùng của bạn.

Trong một số trường hợp, liên kết tài khoản dựa trên mã thông báo ID có thể không thành công đối với người dùng. Nếu nó làm như vậy vì bất kỳ lý do gì, thì điểm cuối trao đổi mã thông báo của bạn cần phải trả lời bằng lỗi HTTP 401 chỉ định error=linking_error , như ví dụ sau cho thấy:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}
Khi Google nhận được phản hồi lỗi 401 với linking_error , Google sẽ gọi điểm cuối trao đổi mã thông báo của bạn với thông tin sau trong yêu cầu:

  • Tham số intent được đặt để create
  • Một JWT với mã thông báo ID và thông tin hồ sơ của người dùng

Handle account creation via Google Sign-In

When a user needs to create an account on your service, Google makes a request to your token exchange endpoint that specifies intent=create.

The request has the following form:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

response_type=token&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&scope=SCOPES&intent=create&assertion=JWT[&NEW_ACCOUNT_INFO]

Your token exchange endpoint must able to handle the following parameters:

Token endpoint parameters
intent For these requests, the value of this parameter is create.
grant_type The type of token being exchanged. For these requests, this parameter has the value urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion A JSON Web Token (JWT) that provides a signed assertion of the Google user's identity. The JWT contains information that includes the user's Google Account ID, name, and email address.

The JWT within the assertion parameter contains the user's Google Account ID, name, and email address, which you can use to create a new account on your service.

To respond to account creation requests, your token exchange endpoint must perform the steps in the following two sections.

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_verifiedhd 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:

  • email có hậu tố @gmail.com , đây là tài khoản Gmail.
  • email_verified là 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.

Validate user information and create new account

Check whether either of the following conditions are true:

  • The Google Account ID, found in the assertion's sub field, is in your user database.
  • The email address in the assertion matches a user in your user database.

If either condition is true, prompt the user to link their existing account with their Google Account. To do so, respond to the request with an HTTP 401 error that specifies error=linking_error and gives the user's email address as the login_hint. The following is a sample response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "error":"linking_error",
  "login_hint":"foo@bar.com"
}

When Google receives a 401 error response with linking_error, Google sends the user to your authorization endpoint with login_hint as a parameter. The user completes account linking using the OAuth linking flow in their browser.

If neither condition is true, create a new user account with the information provided in the JWT. New accounts don't typically have a password set. It's recommended that you add Google Sign-In to other platforms to enable users to log in with Google across the surfaces of your application. Alternatively, you can email the user a link that starts your password recovery flow to allow the user to set a password to sign in on other platforms.

When the creation is completed, issue an access token and refresh token and return the values in a JSON object in the body of your HTTPS response, like in the following example:

{
  "token_type": "Bearer",
  "access_token": "ACCESS_TOKEN",

  "refresh_token": "REFRESH_TOKEN",

  "expires_in": SECONDS_TO_EXPIRATION
}

Xác thực việc triển khai của bạn

Bạn có thể xác nhận thực hiện của bạn bằng cách sử dụng các sân chơi OAuth 2.0 công cụ.

Trong công cụ, hãy thực hiện các bước sau:

  1. Nhấp vào Cấu hình để mở cửa sổ OAuth 2.0 Configuration.
  2. Trong lĩnh vực dòng chảy OAuth, chọn Client-side.
  3. Trong lĩnh vực OAuth thiết bị đầu cuối, chọn Custom.
  4. Chỉ định điểm cuối OAuth 2.0 của bạn và ID khách hàng mà bạn đã chỉ định cho Google trong các trường tương ứng.
  5. Trong phần Bước 1, không chọn bất kỳ phạm vi của Google. Thay vào đó, hãy để trống trường này hoặc nhập phạm vi hợp lệ cho máy chủ của bạn (hoặc một chuỗi tùy ý nếu bạn không sử dụng phạm vi OAuth). Khi bạn đã hoàn tất, nhấn Authorize API.
  6. Trong các phần Bước 2Bước 3, đi qua các dòng chảy OAuth 2.0 và xác minh rằng mỗi bước hoạt động như dự kiến.

Bạn có thể xác nhận thực hiện của bạn bằng cách sử dụng các tài khoản Google Liên kết Demo công cụ.

Trong công cụ, hãy thực hiện các bước sau:

  1. Nhấp vào Sign-in với nút Google.
  2. Chọn tài khoản bạn muốn liên kết.
  3. Nhập ID dịch vụ.
  4. Tùy ý nhập một hoặc nhiều phạm vi mà bạn sẽ yêu cầu quyền truy cập.
  5. Nhấp vào Bắt đầu Demo.
  6. Khi được nhắc, hãy xác nhận rằng bạn có thể đồng ý và từ chối yêu cầu liên kết.
  7. Xác nhận rằng bạn được chuyển hướng đến nền tảng của mình.