Đăng nhập bằng Google bằng API FedCM

Hướng dẫn này thảo luận về việc thư viện nền tảng Đăng nhập bằng Google sử dụng các API FedCM. Các chủ đề bao gồm Tiến trình và Các bước tiếp theo để cập nhật thư viện có khả năng tương thích ngược, cách Tiến hành đánh giá tác động và xác minh việc đăng nhập của người dùng vẫn hoạt động như dự kiến, cũng như hướng dẫn cập nhật ứng dụng web nếu cần. Các lựa chọn để Quản lý giai đoạn chuyển đổi cùng với cách Yêu cầu trợ giúp cũng được đề cập.

Trạng thái của thư viện

Mọi ứng dụng web mới đều bị chặn sử dụng thư viện nền tảng Đăng nhập bằng Google không còn được dùng nữa, trong khi các ứng dụng đang sử dụng thư viện này có thể tiếp tục cho đến khi có thông báo mới. Chúng tôi chưa xác định ngày ngừng hoạt động (ngày ngừng cung cấp) cuối cùng cho thư viện này. Hãy xem phần Ngừng hỗ trợ và ngừng hoạt động để biết thêm thông tin.

Bản cập nhật tương thích ngược sẽ thêm API FedCM vào thư viện Đăng nhập bằng Google. Mặc dù hầu hết các thay đổi đều liền mạch, nhưng bản cập nhật này sẽ có sự khác biệt đối với lời nhắc người dùng, permissions-policy của iframe và Chính sách bảo mật nội dung (CSP). Những thay đổi này có thể ảnh hưởng đến ứng dụng web của bạn và yêu cầu thay đổi mã ứng dụng cũng như cấu hình trang web.

Trong thời gian chuyển đổi, một tuỳ chọn cấu hình sẽ kiểm soát việc có sử dụng API FedCM trong quá trình đăng nhập của người dùng hay không.

Sau khoảng thời gian chuyển đổi, tất cả ứng dụng web sử dụng thư viện Đăng nhập bằng Google đều bắt buộc phải sử dụng API FedCM.

Dòng thời gian

Lần cập nhật gần đây nhất: Tháng 9 năm 2024

Dưới đây là các ngày và thay đổi ảnh hưởng đến hành vi đăng nhập của người dùng:

  • Tháng 3 năm 2023 Ngừng hỗ trợ thư viện nền tảng Đăng nhập bằng Google.
  • Khoảng thời gian chuyển đổi từ tháng 7 năm 2024 bắt đầu và thư viện nền tảng Đăng nhập bằng Google sẽ hỗ trợ các API FedCM. Theo mặc định, Google kiểm soát tỷ lệ phần trăm yêu cầu đăng nhập của người dùng bằng FedCM trong thời gian này. Các ứng dụng web có thể ghi đè rõ ràng hành vi này bằng tham số use_fedcm.
  • Tháng 3 năm 2025, bắt buộc phải sử dụng các API FedCM của thư viện nền tảng Đăng nhập bằng Google. Sau đó, tham số use_fedcm sẽ bị bỏ qua và tất cả các yêu cầu đăng nhập của người dùng đều sử dụng FedCM.

Các bước tiếp theo

Bạn có thể chọn một trong ba cách sau:

  1. Tiến hành đánh giá tác động và cập nhật ứng dụng web nếu cần. Phương pháp này đánh giá xem các tính năng yêu cầu thay đổi đối với ứng dụng web có đang được sử dụng hay không. Bạn có thể xem hướng dẫn trong phần tiếp theo của hướng dẫn này.
  2. Chuyển sang thư viện Dịch vụ nhận dạng của Google (GIS). Bạn nên chuyển sang thư viện đăng nhập mới nhất và được hỗ trợ. Hãy làm theo hướng dẫn này.
  3. Không làm gì cả. Ứng dụng web của bạn sẽ tự động được cập nhật khi thư viện Đăng nhập bằng Google chuyển sang API FedCM để người dùng đăng nhập. Đây là cách làm ít tốn công sức nhất, nhưng có một số rủi ro người dùng không thể đăng nhập vào ứng dụng web của bạn.

Tiến hành đánh giá tác động

Hãy làm theo các hướng dẫn này để xác định xem ứng dụng web của bạn có thể được cập nhật liền mạch thông qua bản cập nhật tương thích ngược hay không, hoặc liệu có cần thay đổi để tránh người dùng không thể đăng nhập khi thư viện nền tảng Đăng nhập bằng Google áp dụng đầy đủ các API FedCM hay không.

Thiết lập

Bạn cần có API trình duyệt và phiên bản mới nhất của thư viện nền tảng Đăng nhập bằng Google để sử dụng FedCM trong quá trình người dùng đăng nhập.

Trước khi đi sâu hơn:

  • Cập nhật lên phiên bản Chrome mới nhất dành cho máy tính. Chrome cho Android yêu cầu bản phát hành M128 trở lên và không thể kiểm thử bằng các phiên bản cũ hơn.
  • Đặt use_fedcm thành true khi khởi chạy thư viện nền tảng Đăng nhập bằng Google trong ứng dụng web. Thông thường, quá trình khởi chạy sẽ có dạng như sau:
    • gapi.client.init({use_fedcm: true}) hoặc
    • gapi.auth2.init({use_fedcm: true}) hoặc
    • gapi.auth2.authorize({use_fedcm: true}).
  • Làm mất hiệu lực các phiên bản lưu trong bộ nhớ đệm của thư viện nền tảng Đăng nhập bằng Google. Thông thường, bạn không cần thực hiện bước này vì phiên bản mới nhất của thư viện được tải trực tiếp xuống trình duyệt bằng cách đưa api.js, client.js hoặc platform.js vào thẻ <script src> (yêu cầu có thể sử dụng bất kỳ tên gói nào trong số này cho thư viện).

  • Xác nhận chế độ cài đặt OAuth cho mã ứng dụng khách OAuth:

    1. Mở trang Thông tin xác thực của

    2. Xác minh URI của trang web có trong Nguồn gốc JavaScript được uỷ quyền. URI chỉ bao gồm giao thức và tên máy chủ đủ điều kiện. Ví dụ: https://www.example.com.

    3. Bạn có thể trả về thông tin xác thực bằng cách chuyển hướng đến một điểm cuối mà bạn lưu trữ thay vì thông qua lệnh gọi lại JavaScript (không bắt buộc). Nếu vậy, hãy xác minh rằng URI chuyển hướng của bạn có trong URI chuyển hướng được uỷ quyền. URI chuyển hướng bao gồm giao thức, tên máy chủ đủ điều kiện và đường dẫn, đồng thời phải tuân thủ Quy tắc xác thực URI chuyển hướng. Ví dụ: https://www.example.com/auth-receiver

Thử nghiệm

Sau khi làm theo hướng dẫn trong phần Thiết lập:

Tìm yêu cầu thư viện Đăng nhập bằng Google

Kiểm tra xem có cần thay đổi permissions-policy và Content Security Policy hay không bằng cách kiểm tra yêu cầu đối với thư viện nền tảng Đăng nhập bằng Google. Để thực hiện việc này, hãy xác định vị trí yêu cầu bằng tên và nguồn gốc của thư viện:

  • Trong Chrome, hãy mở bảng điều khiển Mạng trong Công cụ của Chrome cho nhà phát triển rồi tải lại trang.
  • Sử dụng các giá trị trong cột Miền và Tên để tìm yêu cầu thư viện:
    • Miền là apis.google.com và
    • Tên là api.js, client.js hoặc platform.js. Giá trị cụ thể của Tên phụ thuộc vào gói thư viện mà tài liệu yêu cầu.

Ví dụ: lọc theo apis.google.com trong cột Miền và platform.js trong cột Tên.

Kiểm tra iframe permissions-policy

Trang web của bạn có thể sử dụng thư viện nền tảng Đăng nhập bằng Google bên trong một iframe trên nhiều nguồn gốc. Nếu có, bạn cần cập nhật.

Sau khi làm theo hướng dẫn Tìm yêu cầu thư viện Đăng nhập bằng Google, hãy chọn yêu cầu thư viện Đăng nhập bằng Google trong bảng điều khiển DevTools Network (Mạng) và tìm tiêu đề Sec-Fetch-Site trong mục Request Headers (Yêu cầu tiêu đề) trong thẻ Headers (Tiêu đề). Nếu giá trị của tiêu đề là:

  • same-sitehoặc same-origin thì các chính sách nhiều nguồn gốc sẽ không áp dụng và bạn không cần thực hiện thay đổi nào.
  • Bạn có thể cần thay đổi cross-origin nếu đang sử dụng iframe.

Cách xác nhận xem có iframe hay không:

  • Chọn bảng điều khiển Elements (Phần tử) trong Chrome DevTools và
  • Sử dụng tổ hợp phím Ctrl-F để tìm iframe trong tài liệu.

Nếu tìm thấy iframe, hãy kiểm tra tài liệu để tìm các lệnh gọi đến hàm gapi.auth2 hoặc lệnh script src tải thư viện Đăng nhập bằng Google trong iframe. Nếu trường hợp này xảy ra:

Lặp lại quy trình này cho mọi iframe trong tài liệu. Bạn có thể lồng các iframe, vì vậy, hãy nhớ thêm lệnh allow vào tất cả iframe gốc xung quanh.

Kiểm tra Chính sách bảo mật nội dung

Nếu trang web của bạn sử dụng Chính sách bảo mật nội dung, bạn có thể cần cập nhật CSP để cho phép sử dụng thư viện Đăng nhập bằng Google.

Sau khi làm theo hướng dẫn Tìm yêu cầu thư viện Đăng nhập bằng Google, hãy chọn yêu cầu thư viện Đăng nhập bằng Google trong bảng điều khiển DevTools Network (Mạng) và tìm tiêu đề Content-Security-Policy trong mục Response Headers (Tiêu đề phản hồi) của thẻ Headers (Tiêu đề).

Nếu không tìm thấy tiêu đề, bạn không cần thay đổi gì. Nếu không, hãy kiểm tra xem có lệnh CSP nào trong số này được xác định trong tiêu đề CSP hay không và cập nhật các lệnh đó bằng cách:

  • Thêm https://apis.google.com/js/, https://accounts.google.com/gsi/ và https://acounts.google.com/o/fedcm/ vào bất kỳ lệnh connect-src, default-src hoặc frame-src nào.

  • Thêm https://apis.google.com/js/bundle-name.js vào lệnh script-src. Thay thế bundle-name.js bằng api.js, client.js hoặc platform.js dựa trên gói thư viện yêu cầu tài liệu.

Kiểm tra các thay đổi về lời nhắc của người dùng

Có một số điểm khác biệt đối với hành vi nhắc người dùng, FedCM thêm một hộp thoại phương thức hiển thị do trình duyệt hiển thị và cập nhật các yêu cầu kích hoạt người dùng.

Hình ảnh hộp thoại phương thức FedCM

Kiểm tra bố cục của trang web để xác nhận rằng hộp thoại phương thức của trình duyệt có thể phủ lên và tạm thời che khuất nội dung cơ bản một cách an toàn. Nếu không, bạn có thể cần điều chỉnh bố cục hoặc vị trí của một số phần tử trên trang web.

Kích hoạt người dùng

FedCM bao gồm các yêu cầu mới về việc kích hoạt người dùng. Việc nhấn nút hoặc nhấp vào đường liên kết là ví dụ về cử chỉ của người dùng cho phép nguồn gốc của bên thứ ba đưa ra yêu cầu mạng hoặc lưu trữ dữ liệu. Với FedCM, trình duyệt sẽ nhắc người dùng đồng ý khi:

  • người dùng đăng nhập vào ứng dụng web lần đầu bằng một phiên bản trình duyệt mới hoặc
  • GoogleAuth.signIn được gọi.

Hiện tại, nếu người dùng đã đăng nhập vào trang web của bạn trước đây, bạn có thể lấy thông tin đăng nhập của người dùng khi khởi chạy thư viện Đăng nhập bằng Google bằng gapi.auth2.init mà không cần người dùng tương tác thêm. Bạn không thể thực hiện việc này nữa trừ phi người dùng đã trải qua quy trình đăng nhập FedCM ít nhất một lần.

Bằng cách chọn sử dụng FedCM và gọi GoogleAuth.signIn, vào lần tiếp theo người dùng đó truy cập vào trang web của bạn, gapi.auth2.init có thể lấy thông tin đăng nhập của người dùng trong quá trình khởi chạy mà không cần người dùng tương tác.

Các trường hợp sử dụng phổ biến

Tài liệu dành cho nhà phát triển về thư viện Đăng nhập bằng Google bao gồm hướng dẫn và mẫu mã cho các trường hợp sử dụng phổ biến. Phần này thảo luận về cách FedCM ảnh hưởng đến hành vi của các nút này.

  • Tích hợp tính năng Đăng nhập bằng Google vào ứng dụng web

    Trong bản minh hoạ này, một phần tử <div> và một lớp hiển thị nút, và đối với người dùng đã đăng nhập, sự kiện onload của trang sẽ trả về thông tin xác thực của người dùng. Người dùng cần tương tác để đăng nhập và thiết lập một phiên mới.

    Lớp g-signin2 sẽ thực hiện việc khởi chạy thư viện bằng cách gọi gapi.load và gapi.auth2.init.

    Một cử chỉ của người dùng, sự kiện onclick của phần tử <div>, gọi auth2.signIn trong khi đăng nhập hoặc auth2.signOut khi đăng xuất.

  • Tạo nút Đăng nhập bằng Google tuỳ chỉnh

    Trong bản minh hoạ 1, các thuộc tính tuỳ chỉnh được dùng để kiểm soát giao diện của nút đăng nhập và đối với người dùng đã đăng nhập, sự kiện onload của trang sẽ trả về thông tin xác thực của người dùng. Người dùng phải tương tác để đăng nhập và thiết lập một phiên mới.

    Quá trình khởi chạy thư viện được thực hiện thông qua một sự kiện onload cho thư viện platform.js và nút này được hiển thị bằng gapi.signin2.render.

    Một cử chỉ của người dùng, nhấn vào nút đăng nhập, gọi auth2.signIn.

    Trong bản minh hoạ hai, một phần tử <div>, các kiểu CSS và một đồ hoạ tuỳ chỉnh được dùng để kiểm soát giao diện của nút đăng nhập. Người dùng phải tương tác để đăng nhập và thiết lập một phiên mới.

    Quá trình khởi chạy thư viện được thực hiện khi tải tài liệu bằng cách sử dụng một hàm bắt đầu gọi gapi.load, gapi.auth2.init và gapi.auth2.attachClickHandler.

    Cử chỉ của người dùng, sự kiện onclick của phần tử <div>, gọi auth2.signIn bằng auth2.attachClickHandler trong quá trình đăng nhập hoặc auth2.signOut khi đăng xuất.

  • Theo dõi trạng thái phiên của người dùng

    Trong bản minh hoạ này, thao tác nhấn nút được dùng để người dùng đăng nhập và đăng xuất. Người dùng phải tương tác để đăng nhập và thiết lập một phiên mới.

    Bạn có thể khởi chạy thư viện bằng cách gọi trực tiếp gapi.load, gapi.auth2.init và gapi.auth2.attachClickHandler() sau khi tải platform.js bằng script src.

    Cử chỉ của người dùng, sự kiện onclick của phần tử <div>, gọi auth2.signIn bằng auth2.attachClickHandler trong quá trình đăng nhập hoặc auth2.signOut khi đăng xuất.

  • Yêu cầu cấp thêm quyền

    Trong bản minh hoạ này, thao tác nhấn nút được dùng để yêu cầu các phạm vi OAuth 2.0 bổ sung, lấy mã truy cập mới và đối với người dùng đã đăng nhập, sự kiện onload của trang sẽ trả về thông tin xác thực của người dùng. Người dùng phải tương tác để đăng nhập và thiết lập một phiên mới.

    Sự kiện onload thực hiện việc khởi chạy thư viện cho thư viện platform.js thông qua lệnh gọi đến gapi.signin2.render.

    Một cử chỉ của người dùng, nhấp vào phần tử <button>, sẽ kích hoạt yêu cầu thêm các phạm vi OAuth 2.0 bằng cách sử dụng googleUser.grant hoặc auth2.signOut khi đăng xuất.

  • Tích hợp tính năng Đăng nhập bằng Google bằng trình nghe

    Trong bản minh hoạ này, đối với người dùng đã đăng nhập, sự kiện onload của trang sẽ trả về thông tin xác thực của người dùng. Người dùng phải tương tác để đăng nhập và thiết lập một phiên mới.

    Quá trình khởi chạy thư viện được thực hiện khi tải tài liệu bằng cách sử dụng một hàm bắt đầu gọi gapi.load, gapi.auth2.init và gapi.auth2.attachClickHandler. Tiếp theo, auth2.isSignedIn.listen và auth2.currentUser.listen được dùng để thiết lập thông báo về các thay đổi đối với trạng thái phiên. Cuối cùng, auth2.SignIn được gọi để trả về thông tin xác thực cho người dùng đã đăng nhập.

    Cử chỉ của người dùng, sự kiện onclick của phần tử <div>, gọi auth2.signIn bằng auth2.attachClickHandler trong quá trình đăng nhập hoặc auth2.signOut khi đăng xuất.

  • Tính năng Đăng nhập bằng Google cho ứng dụng phía máy chủ

    Trong bản minh hoạ này, một cử chỉ của người dùng được dùng để yêu cầu mã xác thực OAuth 2.0 và lệnh gọi lại JS thực hiện lệnh gọi AJAX để gửi phản hồi đến máy chủ phụ trợ nhằm xác minh.

    Quá trình khởi chạy thư viện được thực hiện bằng cách sử dụng một sự kiện onload cho thư viện platform.js. Thư viện này sử dụng một hàm bắt đầu để gọi gapi.load và gapi.auth2.init.

    Một cử chỉ của người dùng, nhấp vào một phần tử <button>, sẽ kích hoạt yêu cầu mã uỷ quyền bằng cách gọi auth2.grantOfflineAccess.

  • SSO trên nhiều nền tảng

    FedCM yêu cầu sự đồng ý cho mọi phiên bản trình duyệt, ngay cả khi người dùng Android đã đăng nhập, bạn vẫn cần phải có sự đồng ý một lần.

Quản lý giai đoạn chuyển đổi

Trong giai đoạn chuyển đổi, một tỷ lệ phần trăm số lượt đăng nhập của người dùng có thể sử dụng FedCM, tỷ lệ phần trăm chính xác có thể khác nhau và có thể thay đổi theo thời gian. Theo mặc định, Google kiểm soát số lượng yêu cầu đăng nhập sử dụng FedCM, nhưng bạn có thể chọn sử dụng hoặc không sử dụng FedCM trong thời gian chuyển đổi. Khi kết thúc giai đoạn chuyển đổi, FedCM sẽ trở thành yêu cầu bắt buộc và được dùng cho tất cả các yêu cầu đăng nhập.

Khi chọn sử dụng, người dùng sẽ được đưa đến quy trình đăng nhập FedCM, còn khi chọn không sử dụng, người dùng sẽ được đưa đến quy trình đăng nhập hiện có. Hành vi này được kiểm soát bằng cách sử dụng tham số use_fedcm.

Chọn sử dụng

Bạn nên kiểm soát việc tất cả hay một số lượt đăng nhập vào trang web của mình có sử dụng API FedCM hay không. Để thực hiện việc này, hãy đặt use_fedcm thành true khi khởi chạy thư viện nền tảng. Yêu cầu đăng nhập của người dùng sử dụng các API FedCM trong trường hợp này.

Chọn không sử dụng

Trong thời gian chuyển đổi, một tỷ lệ phần trăm số lượt đăng nhập của người dùng vào trang web của bạn sẽ sử dụng API FedCM theo mặc định. Nếu cần thêm thời gian để thay đổi ứng dụng, bạn có thể tạm thời chọn không sử dụng các API FedCM. Để thực hiện việc này, hãy đặt use_fedcm thành false khi khởi chạy thư viện nền tảng. Yêu cầu đăng nhập của người dùng sẽ không sử dụng API FedCM trong trường hợp này.

Sau khi việc áp dụng bắt buộc diễn ra, mọi chế độ cài đặt use_fedcm sẽ bị thư viện nền tảng Đăng nhập bằng Google bỏ qua.

Nhận trợ giúp

Tìm kiếm hoặc đặt câu hỏi trên StackOverflow bằng thẻ google-signin.