Di chuyển từ tính năng Đăng nhập bằng Google

Hướng dẫn này giúp bạn hiểu những thay đổi và bước cần thiết để di chuyển thành công các thư viện JavaScript từ thư viện nền tảng Đăng nhập bằng Google cũ sang thư viện Dịch vụ nhận dạng của Google mới hơn để xác thực.

Nếu ứng dụng của bạn đang sử dụng Thư viện ứng dụng API của Google cho JavaScript hoặc các thư viện cũ khác để uỷ quyền, hãy xem phần Di chuyển sang Dịch vụ nhận dạng của Google để biết thêm thông tin.

Xác thực và uỷ quyền

Xác thực xác định danh tính của một người và thường được gọi là đăng ký hoặc đăng nhập của người dùng. Uỷ quyền là quá trình cấp hoặc từ chối quyền truy cập vào dữ liệu hoặc tài nguyên. Ví dụ: ứng dụng của bạn yêu cầu người dùng đồng ý để truy cập vào Google Drive của người dùng.

Giống như thư viện nền tảng Đăng nhập bằng Google trước đó, thư viện Dịch vụ nhận dạng của Google mới được xây dựng để hỗ trợ cả quy trình xác thực và uỷ quyền.

Tuy nhiên, thư viện mới hơn tách biệt hai quy trình này để giảm bớt sự phức tạp cho nhà phát triển khi tích hợp Tài khoản Google với ứng dụng của bạn.

Nếu trường hợp sử dụng của bạn chỉ liên quan đến việc xác thực, hãy tiếp tục đọc trang này.

Nếu trường hợp sử dụng của bạn bao gồm việc uỷ quyền, hãy đọc bài viết Cách hoạt động của việc uỷ quyền người dùng và Di chuyển sang Dịch vụ nhận dạng của Google để đảm bảo ứng dụng của bạn đang sử dụng các API mới và cải tiến.

Những điểm thay đổi

Đối với người dùng, thư viện Dịch vụ nhận dạng của Google mới mang đến nhiều điểm cải tiến về khả năng hữu dụng. Những điểm nổi bật bao gồm:

• Quy trình đăng nhập Tự động và Một lần chạm mới có ít bước hơn,
• nút đăng nhập mới được làm mới với tính năng cá nhân hoá cho người dùng,
• việc sử dụng thương hiệu nhất quán và hành vi đăng nhập đồng nhất trên web giúp người dùng hiểu rõ và tin tưởng hơn,
• truy cập nhanh vào nội dung; người dùng có thể đăng ký và đăng nhập trực tiếp từ bất kỳ vị trí nào trên trang web của bạn mà không cần phải truy cập vào trang đăng nhập hoặc trang tài khoản.

Đối với nhà phát triển, chúng tôi tập trung vào việc giảm độ phức tạp, cải thiện tính bảo mật và giúp bạn tích hợp nhanh nhất có thể. Một số điểm cải tiến như sau:

• Lựa chọn thêm tính năng đăng nhập của người dùng vào nội dung tĩnh của trang web chỉ bằng HTML,
• việc tách biệt quy trình xác thực đăng nhập khỏi quy trình uỷ quyền và chia sẻ dữ liệu người dùng, bạn không cần phải tích hợp OAuth 2.0 phức tạp để đăng nhập người dùng vào trang web của mình nữa,
• cả chế độ cửa sổ bật lên và chế độ chuyển hướng đều tiếp tục được hỗ trợ, nhưng cơ sở hạ tầng OAuth 2.0 của Google hiện chuyển hướng đến điểm cuối đăng nhập của máy chủ phụ trợ,
• hợp nhất các tính năng của cả thư viện Google Identity và thư viện JavaScript API của Google trước đó vào một thư viện mới duy nhất,
• đối với các phản hồi đăng nhập, giờ đây, bạn có thể quyết định có sử dụng Promise hay không và đã xoá tính năng gián tiếp thông qua các hàm kiểu getter để đơn giản hoá.

Ví dụ về việc di chuyển thông tin đăng nhập

Nếu bạn đang di chuyển từ nút Đăng nhập bằng Google hiện có và chỉ muốn người dùng đăng nhập vào trang web của bạn, thì thay đổi đơn giản nhất là cập nhật lên nút được cá nhân hoá mới. Bạn có thể thực hiện việc này bằng cách hoán đổi các thư viện JavaScript và cập nhật cơ sở mã để sử dụng đối tượng đăng nhập mới.

Thư viện và cấu hình

Thư viện nền tảng Đăng nhập bằng Google trước đây: apis.google.com/js/platform.js và thư viện ứng dụng API của Google cho JavaScript: gapi.client không còn bắt buộc để xác thực và uỷ quyền người dùng nữa. Các thư viện JavaScript mới này đã được thay thế bằng một thư viện JavaScript mới cho Dịch vụ nhận dạng của Google: accounts.google.com/gsi/client.

Ba mô-đun JavaScript trước đó: api, client và platform dùng để đăng nhập đều được tải từ apis.google.com. Để giúp bạn xác định vị trí có thể chứa thư viện cũ trong trang web của mình, thường là:

• nút đăng nhập mặc định sẽ tải apis.google.com/js/platform.js,
• một đồ hoạ nút tuỳ chỉnh sẽ tải apis.google.com/js/api:client.js và
• việc sử dụng trực tiếp gapi.client sẽ tải apis.google.com/js/api.js.

Trong hầu hết các trường hợp, bạn có thể tiếp tục sử dụng thông tin xác thực Mã ứng dụng của ứng dụng web hiện có. Trong quá trình di chuyển, bạn nên xem lại Chính sách của OAuth 2.0 và sử dụng Bảng điều khiển API của Google để xác nhận và cập nhật các chế độ cài đặt ứng dụng sau (nếu cần):

• ứng dụng thử nghiệm và phát hành chính thức của bạn sử dụng các Dự án riêng biệt và có Mã ứng dụng riêng,
• Loại mã ứng dụng khách OAuth 2.0 là "Ứng dụng web" và
• HTTPS được dùng cho các nguồn gốc JavaScript được uỷ quyền và URI chuyển hướng.

Xác định mã và kiểm thử bị ảnh hưởng

Cookie gỡ lỗi có thể giúp xác định vị trí mã bị ảnh hưởng và kiểm thử hành vi sau khi ngừng sử dụng.

Trong các ứng dụng lớn hoặc phức tạp, bạn có thể khó tìm thấy tất cả mã bị ảnh hưởng khi mô-đun gapi.auth2 không còn được dùng nữa. Để ghi lại việc sử dụng hiện tại của các tính năng sắp ngừng hoạt động vào bảng điều khiển, hãy đặt giá trị của cookie G_AUTH2_MIGRATION thành informational. Nếu muốn, hãy thêm dấu hai chấm, theo sau là giá trị khoá để cũng ghi nhật ký vào bộ nhớ phiên. Sau khi đăng nhập và nhận thông tin xác thực, hãy xem xét hoặc gửi nhật ký đã thu thập đến phần phụ trợ để phân tích sau. Ví dụ: informational:showauth2use lưu nguồn gốc và URL vào khoá bộ nhớ phiên có tên là showauth2use.

Để xác minh hành vi của ứng dụng khi mô-đun gapi.auth2 không còn được tải, hãy đặt giá trị của cookie G_AUTH2_MIGRATION thành enforced. Điều này cho phép kiểm thử hành vi sau khi ngừng sử dụng trước ngày thực thi.

Các giá trị cookie G_AUTH2_MIGRATION có thể có:

• enforced Không tải mô-đun gapi.auth2.
• informational Ghi lại việc sử dụng các tính năng không dùng nữa vào bảng điều khiển JS. Ngoài ra, hãy ghi nhật ký vào bộ nhớ phiên khi tên khoá không bắt buộc được đặt: informational:key-name.

Để giảm thiểu tác động đến người dùng, trước tiên, bạn nên đặt cookie này trên máy trong quá trình phát triển và kiểm thử, trước khi sử dụng cookie này trong môi trường phát hành chính thức.

HTML và JavaScript

Trong trường hợp đăng nhập chỉ xác thực này, mã ví dụ và bản kết xuất của nút Đăng nhập bằng Google hiện có sẽ xuất hiện. Chọn chế độ Cửa sổ bật lên hoặc Chuyển hướng để xem sự khác biệt trong cách xử lý phản hồi xác thực bằng lệnh gọi lại JavaScript hoặc bằng lệnh chuyển hướng bảo mật đến điểm cuối đăng nhập máy chủ phụ trợ.

Cách trước

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Cách mới

Để sử dụng thư viện mới trong trường hợp đăng nhập chỉ dùng để xác thực, hãy chọn chế độ Cửa sổ bật lên hoặc Chuyển hướng và sử dụng mã mẫu để thay thế cách triển khai hiện có trên trang đăng nhập của bạn.

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

Trong ví dụ chỉ xác thực này, thư viện accounts.google.com/gsi/client, lớp g_id_signin và đối tượng g_id_onload mới sẽ thay thế thư viện apis.google.com/js/platform.js và đối tượng g-signin2 trước đó.

Ngoài việc hiển thị nút cá nhân hoá mới, mã ví dụ còn cho thấy cửa sổ bật lên "Một lần chạm" mới. Bất cứ khi nào hiển thị nút được cá nhân hoá, bạn cũng nên hiển thị cửa sổ bật lên Một lần nhấn để giảm thiểu sự phiền hà cho người dùng trong quá trình đăng ký và đăng nhập.

Mặc dù không nên làm như vậy do tăng độ trễ khi đăng nhập, nhưng bạn có thể hiển thị riêng nút cá nhân hoá mới mà không cần hiển thị đồng thời hộp thoại Một lần nhấn. Để thực hiện việc này, hãy đặt thuộc tính data-auto_prompt thành false.

API HTML và JavaScript

Ví dụ trước cho thấy cách sử dụng HTML API mới để thêm tính năng đăng nhập vào trang web. Ngoài ra, bạn có thể dùng API JavaScript có chức năng tương đương hoặc kết hợp và so khớp các API HTML và JavaScript trên trang web của mình.

Để xem các lựa chọn tuỳ chỉnh nút có tính tương tác, chẳng hạn như loại lệnh gọi lại và các thuộc tính như: màu sắc, kích thước, hình dạng, văn bản và giao diện, hãy xem bài viết Trình tạo mã của chúng tôi. Bạn có thể sử dụng công cụ này để nhanh chóng so sánh các tuỳ chọn và tạo đoạn mã HTML để sử dụng trên trang web của mình.

Đăng nhập từ bất kỳ trang nào bằng tính năng Một lần chạm

Tính năng Đăng nhập/đăng ký bằng một lần chạm là một cách mới giúp người dùng đăng ký hoặc đăng nhập vào trang web của bạn một cách dễ dàng. Việc này cho phép bạn cho phép người dùng đăng nhập ngay trên bất kỳ trang nào trên trang web của bạn mà không cần phải truy cập vào một trang đăng nhập riêng. Nói cách khác, việc này giúp giảm sự phiền hà khi đăng ký và đăng nhập bằng cách cho phép người dùng linh hoạt đăng ký và đăng nhập từ các trang khác ngoài trang đăng nhập.

Để cho phép đăng nhập từ bất kỳ trang nào, bạn nên đưa g_id_onload vào tiêu đề, chân trang được chia sẻ hoặc đối tượng khác có trên toàn bộ trang web của mình.

Bạn cũng nên thêm g_id_signin để hiển thị nút đăng nhập được cá nhân hoá chỉ trên trang đăng nhập hoặc trang quản lý tài khoản người dùng. Cho phép người dùng lựa chọn đăng ký hoặc đăng nhập bằng cách hiển thị nút này cùng với các nút nhà cung cấp danh tính liên kết khác, cũng như các trường nhập tên người dùng và mật khẩu.

Phản hồi bằng mã thông báo

Quy trình đăng nhập của người dùng không còn yêu cầu bạn phải hiểu hoặc thao tác với mã uỷ quyền, mã truy cập hoặc mã làm mới OAuth 2.0 nữa. Thay vào đó, Mã thông báo mã nhận dạng web JSON (JWT) sẽ được dùng để chia sẻ trạng thái đăng nhập và hồ sơ người dùng. Để đơn giản hoá hơn, bạn không còn phải sử dụng các phương thức truy cập kiểu "getter" để làm việc với dữ liệu hồ sơ người dùng nữa.

Thông tin xác thực mã thông báo mã nhận dạng JWT bảo mật do Google ký sẽ được trả về:

• đến trình xử lý gọi lại JavaScript dựa trên trình duyệt của người dùng ở chế độ Cửa sổ bật lên hoặc
• đến máy chủ phụ trợ của bạn thông qua lệnh chuyển hướng của Google đến điểm cuối đăng nhập khi nút Đăng nhập bằng Google ux_mode được đặt thành redirect.

Trong cả hai trường hợp, hãy cập nhật trình xử lý lệnh gọi lại hiện có bằng cách xoá:

• cuộc gọi đến googleUser.getBasicProfile(),
• tham chiếu đến BasicProfile và các lệnh gọi liên kết đến phương thức getId(), getName(), getGivenName(), getFamilyName(), getImageUrl(), getEmail() và
• cách sử dụng đối tượng AuthResponse.

Thay vào đó, hãy sử dụng các tệp tham chiếu trực tiếp đến các trường con credential trong đối tượng JWT mới CredentialResponse để xử lý dữ liệu hồ sơ người dùng.

Ngoài ra, và chỉ dành cho chế độ Chuyển hướng, hãy nhớ ngăn chặn Hành vi giả mạo yêu cầu trên nhiều trang web (CSRF) và Xác minh mã thông báo mã nhận dạng của Google trên máy chủ phụ trợ.

Để hiểu rõ hơn về cách người dùng tương tác với trang web của bạn, bạn có thể sử dụng trường select_by trong CredentialResponse để xác định kết quả về sự đồng ý của người dùng và quy trình đăng nhập cụ thể được sử dụng.

Sự đồng ý của người dùng và việc thu hồi quyền

Trong lần đầu tiên người dùng đăng nhập vào trang web của bạn, Google sẽ nhắc người dùng đồng ý chia sẻ hồ sơ tài khoản của họ với ứng dụng của bạn. Chỉ sau khi người dùng đồng ý, hồ sơ của họ mới được chia sẻ với ứng dụng của bạn trong trọng tải thông tin xác thực mã thông báo nhận dạng. Việc thu hồi quyền truy cập vào hồ sơ này tương đương với việc thu hồi mã thông báo truy cập trong thư viện đăng nhập trước đó.

Người dùng có thể thu hồi quyền và ngắt kết nối ứng dụng của bạn khỏi Tài khoản Google của họ bằng cách truy cập vào https://myaccount.google.com/permissions. Ngoài ra, các ứng dụng này có thể ngắt kết nối trực tiếp với ứng dụng của bạn bằng cách kích hoạt lệnh gọi API mà bạn triển khai; phương thức disconnect trước đó đã được thay thế bằng phương thức revoke mới hơn.

Khi người dùng xoá tài khoản của họ trên nền tảng của bạn, tốt nhất bạn nên sử dụng revoke để ngắt kết nối ứng dụng của bạn với Tài khoản Google của họ.

Trước đây, bạn có thể sử dụng auth2.signOut() để quản lý việc người dùng đăng xuất khỏi ứng dụng. Bạn nên xoá mọi hoạt động sử dụng auth2.signOut() và ứng dụng của bạn nên trực tiếp quản lý trạng thái phiên và trạng thái đăng nhập của từng người dùng.

Trạng thái phiên và Trình nghe

Thư viện mới không duy trì trạng thái đã đăng nhập hoặc trạng thái phiên cho ứng dụng web của bạn.

Trạng thái đăng nhập của Tài khoản Google, trạng thái phiên và trạng thái đăng nhập của ứng dụng là các khái niệm riêng biệt, khác nhau.

Trạng thái đăng nhập của người dùng vào Tài khoản Google của họ và ứng dụng của bạn độc lập với nhau, ngoại trừ trong chính thời điểm đăng nhập khi bạn biết rằng người dùng đã xác thực thành công và đăng nhập vào Tài khoản Google của họ.

Khi bạn cung cấp tính năng Đăng nhập bằng Google, Đăng nhập bằng một lần chạm hoặc Đăng nhập tự động trên trang web, trước tiên, người dùng phải đăng nhập vào Tài khoản Google của họ để:

• đồng ý chia sẻ hồ sơ người dùng của họ khi đăng ký hoặc đăng nhập vào trang web của bạn lần đầu tiên,
• và sau đó để đăng nhập khi họ quay lại trang web của bạn.

Người dùng có thể vẫn ở trạng thái đăng nhập, đăng xuất hoặc chuyển sang một Tài khoản Google khác trong khi vẫn duy trì phiên đăng nhập đang hoạt động trên trang web của bạn.

Giờ đây, bạn có trách nhiệm trực tiếp quản lý trạng thái đã đăng nhập cho người dùng ứng dụng web. Trước đây, tính năng Đăng nhập bằng Google đã giúp Theo dõi trạng thái phiên của người dùng.

Xoá mọi tham chiếu đến auth2.attachClickHandler() và trình xử lý gọi lại đã đăng ký của lớp này.

Trước đây, Trình nghe được dùng để chia sẻ các thay đổi về trạng thái đã đăng nhập cho Tài khoản Google của người dùng. Chúng tôi không còn hỗ trợ trình nghe nữa.

Xoá mọi nội dung tham chiếu đến listen(), auth2.currentUser và auth2.isSignedIn.

Bánh quy

Tính năng Đăng nhập bằng Google sử dụng cookie ở mức hạn chế. Sau đây là nội dung mô tả về các cookie này. Hãy xem bài viết Cách Google sử dụng cookie để biết thêm thông tin về các loại cookie khác mà Google sử dụng.

Cookie G_ENABLED_IDPS do Thư viện nền tảng Đăng nhập bằng Google trước đây đặt không còn được sử dụng nữa.

Thư viện Dịch vụ nhận dạng của Google mới có thể đặt các cookie trên nhiều miền này (không bắt buộc) dựa trên các tuỳ chọn cấu hình của bạn:

• g_state lưu trữ trạng thái đăng xuất của người dùng và được đặt khi sử dụng cửa sổ bật lên Một lần chạm hoặc tính năng Tự động đăng nhập,

• g_csrf_token là một cookie gửi hai lần dùng để ngăn chặn các cuộc tấn công CSRF và được đặt khi điểm cuối đăng nhập của bạn được gọi. Bạn có thể đặt giá trị cho URI đăng nhập một cách rõ ràng hoặc có thể đặt giá trị mặc định là URI của trang hiện tại. Điểm cuối đăng nhập của bạn có thể được gọi theo các điều kiện sau khi sử dụng:

  • HTML API với data-ux_mode=redirect hoặc khi đặt data-login_uri hoặc

  • API JavaScript với ux_mode=redirect và trong đó google.accounts.id.prompt() không được dùng để hiển thị tính năng Một lần chạm hoặc Tự động đăng nhập.

Nếu bạn có một dịch vụ quản lý cookie, hãy nhớ thêm hai cookie mới và xoá cookie trước đó khi quá trình di chuyển hoàn tất.

Nếu bạn quản lý nhiều miền hoặc miền con, hãy xem phần Hiển thị một lần chạm trên các miền con để được hướng dẫn thêm về cách làm việc với cookie g_state.

Tài liệu tham khảo về việc di chuyển đối tượng để đăng nhập người dùng