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 rõ 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 để xác thực.

Nếu ứng dụng của bạn đang dùng Thư viện ứng dụng API của Google cho JavaScript hoặc các thư viện cũ hơn 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 ý cho phép ứng dụ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 đây, 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 sẽ tách hai quy trình này để giảm độ 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 cả việc uỷ quyền, hãy đọc bài viết Cách hoạt động của quy trình 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 sử dụng. Các điểm nổi bật bao gồm:

• Quy trình Đăng nhập bằng một lần nhấn và Tự động đăng nhập mới có ít bước riêng lẻ hơn,
• nút đăng nhập mới có tính năng cá nhân hoá người 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 cải thiện sự hiểu biết và niềm tin,
• nhanh chóng truy cập vào nội dung; người dùng có thể đăng ký và đăng nhập trực tiếp từ mọi nơi 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 trước.

Đố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 thiệ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à việc chia sẻ dữ liệu người dùng, không còn cần thiết 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 bạn,
• 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 chức năng của cả hai thư viện JavaScript Google API và Google Identity trước đó thành 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à việc gián tiếp thông qua các hàm kiểu getter đã bị xoá để đơn giản hoá.

Ví dụ về việc di chuyển quy trình đă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ỉ quan tâm đến việc đăng nhập người dùng vào trang web của mình, 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 một đố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 Google API cho JavaScript: gapi.client không còn bắt buộc đối với việc xác thực và uỷ quyền người dùng nữa. Các thư viện này đã được thay thế bằng một thư viện JavaScript duy nhất mới của 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 những vị trí mà thư viện cũ có thể xuất hiện trên trang web của bạn, thường thì:

• nút đăng nhập mặc định tải apis.google.com/js/platform.js,
• một hình ảnh nút tuỳ chỉnh 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 đăng nhập Client ID của ứng dụng web hiện có. Trong quá trình di chuyển, bạn nên xem xét Chính sách OAuth 2.0 của chúng tôi và sử dụng Google API Console để xác nhận, đồng thời cập nhật (nếu cần) các chế độ cài đặt sau đây cho ứng dụng:

• ứng dụng thử nghiệm và ứng dụng phát hành công khai 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 OAuth 2.0 là "Ứng dụng web" và
• HTTPS được dùng cho các gốc JavaScript được phép và URI chuyển hướng.

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

Cookie gỡ lỗi có thể giúp xác định 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ể gặp khó khăn khi tìm tất cả mã bị ảnh hưởng bởi việc ngừng sử dụng mô-đun gapi.auth2. Để ghi lại việc sử dụng các chức năng hiện có sắp bị ngừng sử dụ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à một giá trị khoá để cũng ghi vào bộ nhớ phiên. Sau khi đăng nhập và nhận được thông tin đăng nhập, hãy xem xét hoặc gửi nhật ký đã thu thập đến một dịch vụ phụ trợ để phân tích sau. Ví dụ: informational:showauth2use lưu nguồn gốc và URL vào một khoá lưu trữ 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 bạn 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 nhật ký việc sử dụng các chức năng không dùng nữa vào bảng điều khiển JS. Cũng ghi vào bộ nhớ phiên khi bạn đặt tên khoá không bắt buộc: 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 cục bộ trong quá trình phát triển và thử nghiệm, trước khi sử dụng trong môi trường sản xuất.

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ế độ bật lên hoặc chuyển hướng để xem sự khác biệt về 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 cách chuyển hướng an toàn đến điểm cuối đăng nhập của 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 thức mới

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

<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 cá nhân hoá mới, mã ví dụ cũng hiển thị cửa sổ bật lên mới của tính năng Đăng nhập bằng một lần nhấn. Bất cứ nơi nào bạn 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 Đăng nhập bằng một lần nhấn để giảm thiểu sự bất tiện cho người dùng trong quá trình đăng ký và đăng nhập.

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

HTML và JavaScript API

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 của bạn. Ngoài ra, bạn có thể sử dụng JavaScript API tương đương về chức năng hoặc kết hợp HTML và JavaScript API trên trang web của mình.

Để xem các lựa chọn tuỳ chỉnh nút một cách tương tác, chẳng hạn như loại 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 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 lựa chọn khác nhau và tạo đoạn mã HTML để sử dụng trên trang web của mình.

Đăng nhập từ mọi trang bằng tính năng Một lần nhấn

One Tap là một cách thức mới, ít phiền hà để người dùng đăng ký hoặc đăng nhập vào trang web của bạn. Tính năng này cho phép bạn bật tính năng đăng nhập của người dùng ngay từ bất kỳ trang nào trên trang web của bạn và loại bỏ nhu cầu người dùng phải truy cập vào một trang đăng nhập chuyên dụng. Nói cách khác, điều 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 của bạn.

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

Bạn cũng nên thêm g_id_signin (chỉ hiển thị nút đăng nhập được cá nhân hoá) trên các trang đăng nhập hoặc trang quản lý tài khoản người dùng. Cung cấp cho 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 dịch vụ danh tính liên kết khác và 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

Bạn không cần phải hiểu hoặc làm việc với mã uỷ quyền, mã truy cập hoặc mã làm mới OAuth 2.0 để người dùng đăng nhập. Thay vào đó, Mã thông báo nhận dạng Mã thông báo web JSON (JWT) đượ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 nữa, bạn không còn phải sử dụng các phương thức truy cập theo kiểu "getter" để xử lý dữ liệu hồ sơ người dùng.

Thông tin đăng nhập mã thông báo nhận dạng JWT được Google ký an toàn sẽ được trả về theo một trong hai cách:

• đế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 một 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(),
• các tham chiếu đến BasicProfile và các lệnh gọi được liên kết đến các 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 tham chiếu trực tiếp đến các trường phụ credential trong đối tượng JWT CredentialResponse mới để 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 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ả 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

Khi người dùng đăng nhập vào trang web của bạn lần đầu tiê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 tải trọng thông tin đăng nhập của 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ã 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, họ có thể ngắt kết nối trực tiếp khỏi ứng dụng của bạn bằng cách kích hoạt mộ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, cách tốt nhất là bạn nên sử dụng revoke để ngắt kết nối ứng dụng của bạn khỏi Tài khoản Google của họ.

Trước đây, bạn có thể dùng auth2.signOut() để giúp quản lý việc đăng xuất của người dùng khỏi ứng dụng. Bạn nên xoá mọi cách 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à những khái niệm riêng biệt.

Trạng thái đăng nhập của người dùng vào Tài khoản Google và ứng dụng của bạn là độ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 thêm 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 vào trang web của mình, trước tiên, người dùng phải đăng nhập vào Tài khoản Google để:

• đồ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 vào những lần truy cập tiếp theo vào trang web của bạn.

Người dùng có thể duy trì 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ì một phiên hoạt động đã đăng nhập trên trang web của bạn.

Giờ đây, bạn chịu trách nhiệm trực tiếp quản lý trạng thái đăng nhập của 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 thông tin tham chiếu đến auth2.attachClickHandler() và trình xử lý lệnh gọi lại đã đăng ký của nó.

Trước đây, Listeners đượ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. Không còn hỗ trợ trình nghe nữa.

Xoá mọi tệp 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ề những cookie này. Hãy xem 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.

Không còn sử dụng cookie G_ENABLED_IDPS do Thư viện nền tảng đăng nhập bằng Google trước đó đặt.

Thư viện Dịch vụ nhận dạng của Google mới có thể tuỳ ý đặt các cookie trên nhiều miền này dựa trên các lựa 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 nhấn hoặc tính năng Tự động đăng nhập,

• g_csrf_token là một cookie gửi hai lần được 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ể 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 trong những điều kiện sau khi sử dụng:

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

  • JavaScript API có ux_mode=redirect và nơi không dùng google.accounts.id.prompt() để 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 2 cookie mới và xoá cookie 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 bài viết Hiển thị tính năng Đăng nhập một lần trên các miền con để biết thêm hướng dẫn về cách sử dụng cookie g_state.

Thông tin tham khảo về việc di chuyển đối tượng để đăng nhập người dùng