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

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 .

Tạo dự án

Để tạo dự án của bạn để sử dụng liên kết tài khoản:

  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 .

Quy trình Liên kết tài khoản Google bao gồm 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ẽ cần phải định cấu hình màn hình chấp thuận OAuth của mình trước khi tạo ID ứng dụng khách API Google.

  1. Mở trang màn hình chấp thuận OAuth của bảng điều khiển API của Google.
  2. Nếu được nhắc, hãy chọn dự án bạn vừa tạo.
  3. Trên trang "Màn hình chấp thuận OAuth", hãy điền vào biểu mẫu và nhấp vào nút "Lưu".

    Application name: Tên của đơn xin đồng ý. Tên 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 ở những 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 ứ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 được hiển thị trên màn hình đồng ý liên kết tài khoản và trên cài đặt tài khoản

    Email hỗ trợ: Để 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 dành cho API của 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. Thông thường, cách tốt nhất là yêu cầu phạm vi tăng dần, tại thời điểm bắt buộc phải truy cập, thay vì lên trước. Tìm hiểu thêm .

    Miền được ủy quyền: Để bảo vệ bạn và người dùng của bạn, 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. Các liên kết ứng dụng của bạn phải được lưu trữ trên Miền được ủy quyền. Tìm hiểu thêm .

    Liên kết 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 ủy quyền.

    Liên kết Chính sách Bảo mật của Ứng dụng: Hiển thị trên màn hình đồng ý của Liên kết Tài khoản Google. Phải được lưu trữ trên một miền được ủy quyền.

    Liên kết Điều khoản dịch vụ của ứng dụng (Tùy chọn): Phải được lưu trữ trên Miền được ủy quyền.

    Hình 1 . Màn hình đồng ý liên kết tài khoản Google cho một ứng dụng hư cấu, Tunery

  4. Kiểm tra "Trạng thái xác minh", nếu ứng dụng của bạn cần xác minh thì nhấp vào nút "Gửi để xác minh" để gửi đơn đăng ký của bạn để xác minh. Tham khảo yêu cầu xác minh OAuth để biết thêm chi tiết.

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
    }

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.