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

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

Đă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.

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à thực hiện check , createget ý định.

Theo quy trình ngầm định , Google mở điểm cuối ủy quyền của bạn trong trình duyệt của người dùng. Sau khi đăng nhập thành công, bạn trả lại mã thông báo truy cập tồn tại lâu dài cho Google. Mã thông báo truy cập này hiện được bao gồm trong mọi yêu cầu được gửi từ Google.

Trong luồng mã ủy quyền , bạn cần hai điểm cuối:

  • Điểm cuối ủy 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 của bạn. Điểm cuối ủy quyền cũng tạo mã ủy 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 hai loại trao đổi:

    1. Trao đổi mã ủy quyền lấy mã thông báo làm mới tồn tại lâu và mã thông báo truy cập tồn tại trong thời gian ngắn. Việc 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. Đổi mã thông báo làm mới tồn tại lâu lấy mã thông báo truy cập tồn tại trong thời gian ngắn. Việc trao đổi này xảy ra khi Google cần mã thông báo truy cập mới vì mã này đã hết hạn.

Chọn luồng OAuth 2.0

Mặc dù quy trình ngầm định dễ triển khai hơn, nhưng Google khuyến nghị rằng các mã thông báo truy cập được cấp bởi quy trình ngầm định không bao giờ hết hạn. Điều này là do người dùng buộc phải liên kết lại tài khoản của họ sau khi mã thông báo hết hạn với quy trình ngầm định. Nếu bạn cần hết hạn mã thông báo vì lý do bảo mật, chúng tôi thực sự khuyên bạn nên sử dụng quy trình mã ủy quyền để thay thế.

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

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

Hình này cho thấy các bước để người dùng liên kết tài khoản Google của họ với hệ thống xác thực của bạn. Ảnh chụp màn hình đầu tiên hiển thị liên kết do người dùng khởi tạo từ nền tảng của bạn. Hình ảnh thứ hai cho thấy người dùng đăng nhập vào Google, trong khi hình thứ ba hiển thị sự đồng ý và xác nhận của người dùng đối với việc liên kết tài khoản Google của họ với ứng dụng của bạn. Ảnh chụp màn hình cuối cùng cho thấy một tài khoản người dùng được liên kết thành công trong ứng dụng Google.
Hình 1. Tài khoản liên kết đăng nhập của người dùng với Google và màn hình chấp thuậ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 một sản phẩm cụ thể của Google như Google Home hoặc Google Assistant.

khuyến nghị

Chúng tôi khuyên bạn nên làm như sau:

  1. Hiển thị Chính sách Bảo mật của Google. Bao gồm một liên kết đến Chính sách quyền riêng tư của Google trên màn hình chấp thuận.

  2. Dữ liệu được chia sẻ. Sử dụng ngôn ngữ rõ ràng và ngắn gọn để cho người dùng biết dữ liệu của họ mà Google yêu cầu và lý do tại sao.

  3. Gọi hành động rõ ràng. Nêu lời gọi hành động rõ ràng trên màn hình lấy sự đồng ý của bạn, chẳng hạn như “Đồng ý và liên kết”. Điều này là do người dùng cần hiểu dữ liệu nào họ cần chia sẻ với Google để liên kết tài khoản của họ.

  4. Khả năng hủy bỏ. Cung cấp cách để người dùng quay lại hoặc hủy, nếu họ chọn không liên kết.

  5. Quy trình đăng nhập rõ ràng. Đảm bảo rằng người dùng có phương pháp 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 cho tên người dùng và mật khẩu của họ hoặc Đăng nhập bằng Google .

  6. Khả năng hủy liên kết. Cung cấp cơ chế để người dùng hủy liên kết, chẳng hạn như URL đế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 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ọ.

  7. Khả năng thay đổi tài khoản người dùng. Đề xuất phương pháp để 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 chấp thuận để chuyển đổi tài khoản, hãy gửi lỗi có thể khắc phục cho Google để người dùng có thể đăng nhập vào tài khoản mong muốn bằng liên kết OAuth và quy trình ngầm định .
  8. Bao gồm logo của bạn. Hiển thị logo công ty của bạn trên màn hình chấp thuận. Sử dụng các nguyên tắc phong cách của bạn để đặt logo của bạn. Nếu bạn cũng muốn hiển thị biểu trưng của Google, hãy xem Biểu trưng và nhãn hiệu .

Định cấu hình dự án

Để định cấu hình dự án của bạn để sử dụng liên kết tài khoản OAuth:

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

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

  1. Go to the Google API Console.
  2. 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 .

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

Việc triển khai luồng mã ủy quyền trên máy chủ OAuth 2.0 bao gồm hai điểm cuối mà dịch vụ của bạn cung cấp bởi 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 khởi xướng có quy trình sau:

  1. 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, Google sẽ chuyển quá trình thực hiện 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 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ã ủy quyền và gửi lại 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ã ủy quyền được đính kèm với yêu cầu.
  4. Google gửi mã ủy quyền đến điểm cuối trao đổi mã thông báo của bạn, điểm này xác minh tính xác thực của mã và trả về mã thông báo truy cậpmã làm mới . 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.
  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ã 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 ứng dụng khách Google mà bạn đã đăng ký với 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 tập hợp các chuỗi phạm vi được phân tách bằng dấu cách chỉ định dữ liệu mà Google đang yêu cầu ủy quyền.
response_type Loại giá trị sẽ trả về trong phản hồi. Đối với luồng mã ủy quyền OAuth 2.0, loại phản hồi luôn là code .
user_locale Cài đặt ngôn ngữ Tài khoản Google ở ​​định dạng RFC5646 , được sử dụng để bản địa hóa nội dung của bạn bằng ngôn ngữ ưa thích của người dùng.

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

  1. Xác minh rằng client_id khớp với ID khách hàng Google mà bạn đã đăng ký với 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 bị đị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_typecode .
  2. 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.
  3. 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.
  4. Xác nhận rằng URL được chỉ định bởi tham số redirect_uri 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 được chỉ định bởi tham số redirect_uri . Bao gồm mã ủy 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 code và thông số 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ý 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 làm 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ã mà Google nhận được từ điểm cuối đăng nhập hoặc trao đổi mã thông báo của bạn.
redirect_uri Khi grant_type=authorization_code , thông số này là URL được sử dụng trong yêu cầu ủy quyền ban đầu.
refresh_token Khi grant_type=refresh_token , tham số này là mã làm mới mà Google nhận được từ đ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

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_typeauthorization_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 lấy mã thông báo truy cập và mã thông báo làm mới, điểm cuối trao đổi mã thông báo của bạn 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 yêu cầu là nguồn gốc được ủy quyền và client_secret khớp với giá trị mong đợi.
  2. 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.
  3. Xác nhận rằng URL được chỉ định bởi tham số redirect_uri giống với giá trị được sử dụng trong yêu cầu ủy quyền ban đầu.
  4. Nếu bạn không thể xác minh tất cả các tiêu chí trên, hãy trả về lỗi HTTP 400 Bad Request với phần nội dung là {"error": "invalid_grant"} .
  5. 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. 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 họ 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.
  6. 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",
    "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_typerefresh_token và giá trị của refresh_token là giá trị của mã thông báo 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ã 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ã thông báo làm mới lấy mã thông báo truy cập, điểm cuối trao đổi mã thông báo của bạn 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 yêu cầu là Google và client_secret khớp với giá trị mong đợi.
  2. 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.
  3. Nếu bạn không thể xác minh tất cả các tiêu chí trên, hãy trả về lỗi HTTP 400 Bad Request với phần nội dung là {"error": "invalid_grant"} .
  4. 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 họ 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.
  5. 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
    }

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

Xử lý việc tạo tài khoản thông qua Đăng nhập bằng Google

Khi người dùng cần tạo tài khoản trên dịch vụ của bạn, Google sẽ đưa ra yêu cầu tới điểm cuối trao đổi mã thông báo của bạn để chỉ định intent=create .

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

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]

Đ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 create .
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.

JWT trong tham số assertion chứa ID tài khoản Google, tên và địa chỉ email của người dùng mà bạn có thể sử dụng để tạo tài khoản mới trên dịch vụ của mình.

Để phản hồi các yêu cầu tạo tài khoản, điểm cuối trao đổi mã thông báo của bạn phải thực hiện các bước trong hai phần sau.

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.

Xác thực thông tin người dùng và tạo tài khoản mới

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, hãy nhắc người dùng liên kết tài khoản hiện có với Tài khoản Google của họ. Để làm như vậy, hãy trả lời yêu cầu bằng lỗi HTTP 401 chỉ định error=linking_error và cung cấp địa chỉ email của người dùng làm login_hint . Sau đây là câu trả lời mẫu:

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 người dùng đến điểm cuối ủy quyền của bạn với login_hint làm tham số. Người dùng hoàn tất liên kết tài khoản bằng cách sử dụng quy trình liên kết OAuth trong trình duyệt của họ.

Nếu cả hai điều kiện đều không đúng, hãy tạo một tài khoản người dùng mới với thông tin được cung cấp trong JWT. Các tài khoản mới thường không đặt mật khẩu. Bạn nên thêm Đăng nhập bằng Google vào các nền tảng khác để cho phép người dùng đăng nhập bằng Google trên các giao diện ứng dụng của bạn. Ngoài ra, bạn có thể gửi email cho người dùng một liên kết bắt đầu quy trình khôi phục mật khẩu của bạn để cho phép người dùng đặt mật khẩu để đăng nhập trên các nền tảng khác.

Khi quá trình tạo hoàn tất, hãy cấp mã thông báo truy cập và làm mới mã thông báo và trả về các giá trị trong đối tượng JSON trong phần nội dung phản hồi HTTPS của bạn, như trong ví dụ sau:

{
  "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 thực việc triển khai của mình bằng cách sử dụng công cụ Sân chơi OAuth 2.0 .

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ổ Cấu hình OAuth 2.0.
  2. Trong trường quy trình OAuth , chọn Phía máy khách .
  3. Trong trường Điểm cuối OAuth , hãy chọn Tùy chỉnh .
  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 nào 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, hãy nhấp vào Ủy quyền API .
  6. Trong phần Bước 2Bước 3 , xem qua quy trình OAuth 2.0 và xác minh rằng mỗi bước hoạt động như dự định.

Bạn có thể xác thực việc triển khai của mình bằng cách sử dụng công cụ Demo liên kết tài khoản Google .

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

  1. Nhấp vào nút Đăng nhập bằng 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.