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

Hướng dẫn này giúp bạn nắm được các thay đổi cần thiết và các bước để di chuyển thành công thư viện JavaScript từ thư viện nền tảng Đăng nhập bằng Google trước đó sang thư viện Dịch vụ nhận dạng 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 dành cho JavaScript hoặc các thư viện trước đây để uỷ quyền, hãy xem bài viết 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à hoạt động đă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 sự đồng ý của người dùng để truy cập vào Google Drive của họ.

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à cấp quyền.

Tuy nhiên, thư viện mới sẽ tách 2 quy trình này để đơn giản hoá quá trình nhà phát triển 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 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 có uỷ quyền, hãy đọc Cách hoạt động của quy trình uỷ quyền của 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 sẽ cung cấp nhiều điểm cải tiến về khả năng sử dụng. Những điểm nổi bật bao gồm:

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

Đối với các 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 mức độ bảo mật và giúp quá trình tích hợp diễn ra nhanh nhất có thể. Có thể kể đến một số điểm cải tiến như sau:

• Tuỳ chọn để thêm người dùng đăng nhập vào nội dung tĩnh của trang web chỉ bằng HTML,
• tách biệt hoạt động xác thực đăng nhập khỏi uỷ quyền và chia sẻ dữ liệu người dùng, việc tích hợp OAuth 2.0 không còn phức tạp nữa để đă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à chuyển hướng vẫn 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 từ cả thư viện JavaScript trước đó của Google Identity và thư viện JavaScript của Google API vào một thư viện mới,
• đối với phản hồi đăng nhập, giờ đây bạn có thể quyết định xem có nên sử dụng Promise và gián tiếp thông qua các hàm kiểu phương thức getter đã bị xoá để đơn giản.

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 nhập vào trang web của người dùng, thì thay đổi đơn giản nhất là cập nhật 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 cần thiết cho việc xác thực và uỷ quyền người dùng. Chúng đã được thay thế bằng một thư viện JavaScript mới của Dịch vụ nhận dạng của Google: accounts.google.com/gsi/client.

3 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 các vị trí mà thư viện trước đó có thể được đưa vào trang web của bạn, thường là:

• nút đăng nhập mặc định sẽ tải apis.google.com/js/platform.js,
• một hình ảnh 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 khách 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 OAuth 2.0 và sử dụng Google API Console để xác nhận và nếu cần, hãy cập nhật các chế độ cài đặt ứng dụng sau:

• ứng dụng kiểm thử và ứng dụng 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 khách 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ã bị ảnh hưởng và kiểm thử

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

HTML và JavaScript

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

Cách sớm hơn

<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

Để dùng thư viện mới trong trường hợp đăng nhập chỉ nhằm xác thực, hãy chọn chế độ Cửa sổ bật lên hoặc Chuyển hướng, đồng thời 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 mới, lớp g_id_signin và đối tượng g_id_onload 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ã mẫu cũng hiển thị cửa sổ bật lên mới bằng tính năng Một lần chạm. Bạn nên hiển thị cửa sổ bật lên Một lần chạm ở bất cứ đâu để giảm thiểu sự phiền toái của người dùng trong quá trình đăng ký và đăng nhập.

Mặc dù không nên dùng do việc đăng nhập khó khăn hơn, nhưng nút được cá nhân hoá mới có thể hiển thị riêng biệt mà không cần hiển thị đồng thời hộp thoại Một lần chạm. Để làm 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 biết cách sử dụng HTML API mới để thêm thông tin đăng nhập vào trang web. Ngoài ra, bạn có thể sử dụng API JavaScript có chức năng tương đương hoặc kết hợp các API HTML với JavaScript trên trang web của mình.

Để xem các tuỳ chọn tuỳ chỉnh nút một cách 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 Trình tạo mã của chúng tôi. Mã này có thể được dùng để so sánh nhanh các tuỳ chọn và tạo đoạn mã HTML để sử dụng trên trang web của bạn.

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

Một lần chạm là cách dễ dàng mới để 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 người dùng đăng nhập trực tiếp từ trang bất kỳ trên trang web của bạn và người dùng không cần phải truy cập vào một trang đăng nhập chuyên dụng. Nói một cách khác, tính năng này làm 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 qua các trang khác vớ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 đầu trang, chân trang hoặc đối tượng khác được chia sẻ được đưa vào toàn bộ trang web.

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 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 của nhà cung cấp danh tính được 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

Việc đăng nhập của người dùng không còn yêu cầu bạn hiểu hoặc làm việc với mã uỷ quyền OAuth 2.0, mã truy cập hoặc mã làm mới. Thay vào đó, Mã thông báo 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 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ã 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ý gọi lại hiện có bằng cách xóa:

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

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

Ngoài ra, và chỉ đối với 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ả đồ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à thu hồi quyền

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

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

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.

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 thời điểm đăng nhập khi bạn biết 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 tính năng Đăng nhập bằng Google, tính năng Một lần chạm hoặc tính năng Tự động đăng nhập được áp dụng trên trang web của bạn, 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 lần đầu đăng ký hoặc đăng nhập vào trang web của bạn,
• và sau đó là đăng nhập lại khi truy cập lại vào trang web của bạn.

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

Giờ đây, bạn chịu trách nhiệm quản lý trực tiếp trạng thái đăng nhập cho người dùng ứng dụng web của bạn. Trước đây, tính năng Đăng nhập bằng Google giúp bạn 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à các trình xử lý lệnh gọi lại đã đăng ký của hàm này.

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

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

Bánh quy

Tính năng Đăng nhập bằng Google hạn chế việc sử dụng cookie, dưới đây là nội dung mô tả về các cookie nà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.

Cookie G_ENABLED_IDPS do Thư viện nền tảng đăng nhập bằng Google trước đó đặ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ể tuỳ ý đặt các cookie trên nhiều miền này 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 thiết lập khi sử dụng cửa sổ bật lên bằng Một lần chạm hoặc Đăng nhập tự động,

• 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. Cookie này được thiết lập 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 của mình một cách rõ ràng hoặc đặt 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 các đ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

  • 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 Đăng nhập tự động.

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 bài viết 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ười dùng đăng nhập