Liên kết tài khoản với OAuth

Loại liên kết OAuth hỗ trợ 2 quy trình OAuth 2.0 tiêu chuẩn ngành là quy trình mã ngầm ẩn và uỷ quyền.

Trong luồng mã ngầm định, Google sẽ 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 sẽ trả về một mã thông báo truy cập dài hạn cho Google. Mã thông báo truy cập này hiện được đưa vào mọi yêu cầu gửi từ Trợ lý tới Hành động của bạn.

Trong quy trình mã uỷ quyền, bạn cần có 2 điểm cuối:

• Điểm cuối uỷ quyền (trách nhiệm trình bày giao diện người dùng đăng nhập cho người dùng chưa đăng nhập và ghi lại sự đồng ý đối với quyền truy cập được yêu cầu dưới dạng mã uỷ quyền ngắn hạn).
• Điểm cuối token exchange chịu trách nhiệm về hai hình thức trao đổi:
  1. Trao đổi một mã ủy quyền để lấy mã làm mới trong thời gian dài và một mã truy cập ngắn hạn. Quá trình trao đổi này diễn ra khi người dùng trải qua quy trình liên kết tài khoản.
  2. Trao đổi mã làm mới trong thời gian dài để lấy mã truy cập ngắn hạn. Quá trình trao đổi này diễn ra khi Google cần một mã truy cập mới vì mã này đã hết hạn.

Mặc dù quy trình mã ngầm định đơn giản hơn nên triển khai, bạn nên sử dụng các mã thông báo truy cập được phát hành bằng quy trình ngầm ẩn, vì việc sử dụng mã thông báo hết hạn với luồng ngầm định sẽ buộc người dùng liên kết lại tài khoản của họ. Nếu cần mã hết hạn vì lý do bảo mật, bạn nên cân nhắc sử dụng quy trình mã xác thực.

Lưu ý: Vui lòng chọn quy trình OAuth 2.0 mà bạn muốn triển khai. Nếu cần, nội dung của hướng dẫn này sẽ tải lại để phù hợp với lựa chọn của bạn.

Mã xác thực Quy trình ngầm ẩn

Triển khai liên kết tài khoản OAuth

Lưu ý: Nếu bạn đang triển khai tính năng liên kết tài khoản để xử lý thông tin tài chính, xin lưu ý rằng các chính sách bổ sung có thể áp dụng cho Hành động của bạn. Có thể chúng tôi mất đến 6 tuần để xem xét một Hành động có liên kết tài khoản nhằm thu thập thông tin tài chính. Vì vậy, hãy tính đến thời gian đó khi lên kế hoạch cho lịch phát hành. Để quá trình xem xét diễn ra dễ dàng, hãy đảm bảo bạn tuân thủ các chính sách về dịch vụ tài chính trước khi gửi Hành động đi xem xét.

Định cấu hình dự án

Để định cấu hình dự án nhằm sử dụng tính năng liên kết OAuth, hãy làm theo các bước sau:

1. Mở Bảng điều khiển Actions rồi chọn dự án mà bạn muốn sử dụng.
2. Nhấp vào thẻ Phát triển rồi chọn Liên kết tài khoản.
3. Bật nút chuyển bên cạnh Liên kết tài khoản.
4. Trong phần Tạo tài khoản, hãy chọn Không, tôi chỉ muốn cho phép tạo tài khoản trên trang web của mình.

5. Trong mục Loại liên kết, hãy chọn OAuth và Ngầm ẩn.

   

6. Trong phần Thông tin khách hàng:

   • Chỉ định một giá trị cho Mã ứng dụng khách do Hành động của bạn gửi cho Google để xác định các yêu cầu đến từ Google.
   • Chèn URL cho điểm cuối Uỷ quyền và Trao đổi mã thông báo của bạn.

Lưu ý: Nếu bạn muốn gửi mã ứng dụng khách dưới dạng chuỗi mã hoá base64, hãy nhấp vào mũi tên thả xuống bên cạnh Định cấu hình ứng dụng khách (không bắt buộc) và chọn hộp Google to truyền clientID và secret qua HTTP basic auth header.

6. Nhấp vào Lưu.

Triển khai máy chủ OAuth

Để hỗ trợ luồng ngầm ẩn OAuth 2.0, dịch vụ của bạn sẽ cung cấp một điểm cuối cấp quyền qua HTTPS. Điểm cuối này chịu trách nhiệm xác thực và lấy sự đồng ý của người dùng về việc truy cập dữ liệu. Điểm cuối uỷ quyền hiển thị giao diện người dùng đăng nhập cho người dùng chưa đăng nhập và ghi lại sự đồng ý đối với quyền truy cập đã yêu cầu.

Khi Hành động của bạn cần gọi một trong các API được uỷ quyền của dịch vụ, Google sẽ sử dụng điểm cuối này để được người dùng cho phép gọi các API này thay mặt cho họ.

Một phiên luồng ngầm ẩn OAuth 2.0 thông thường do Google khởi tạo có quy trình sau đây:

1. Google sẽ mở điểm cuối uỷ quyền của bạn trong trình duyệt của người dùng. Người dùng đăng nhập nếu chưa đăng nhập và cấp cho Google quyền truy cập vào dữ liệu của họ bằng API của bạn nếu họ chưa cấp quyền.
2. Dịch vụ của bạn sẽ tạo một mã truy cập và trả lại cho Google bằng cách chuyển hướng trình duyệt của người dùng trở lại Google với mã truy cập được đính kèm với yêu cầu.
3. Google gọi các API của dịch vụ và đính kèm mã truy cập vào từng yêu cầu. Dịch vụ của bạn sẽ xác minh rằng mã truy cập cấp cho Google quyền truy cập vào API, sau đó hoàn tất lệnh gọi API.

Xử lý các yêu cầu uỷ quyền

Khi Hành động của bạn cần thực hiện liên kết tài khoản thông qua một luồng ngầm ẩn OAuth 2.0, Google sẽ chuyển người dùng đó đến điểm cuối ủy quyền của bạn bằng một yêu cầu bao gồm các tham số sau:

Tham số điểm cuối uỷ quyền
client_id	Mã ứng dụng khách mà bạn đã chỉ định cho Google.
redirect_uri	URL mà bạn gửi phản hồi cho yêu cầu này.
state	Một giá trị ghi sổ được trả về cho Google sẽ không thay đổi trong URI chuyển hướng.
response_type	Loại giá trị cần trả về trong phản hồi. Đối với luồng ngầm ẩn OAuth 2.0, loại phản hồi luôn là token.

Ví dụ: nếu điểm cuối uỷ quyền của bạn có sẵn tại https://myservice.example.com/auth, thì yêu cầu có thể có dạng như sau:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token

Để điểm cuối uỷ quyề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 các giá trị client_id và redirect_uri để ngăn việc cấp quyền truy cập vào các ứng dụng khách ngoài ý muốn hoặc bị định cấu hình sai:

   • Xác nhận rằng client_id khớp với mã ứng dụng khách mà bạn đã chỉ định cho Google.
   • Xác nhận rằng URL do tham số redirect_uri chỉ định có dạng sau:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID

     YOUR_PROJECT_ID là mã nhận dạng trên trang Cài đặt dự án của Bảng điều khiển Actions.

2. Kiểm tra xem người dùng có đăng nhập vào dịch vụ của bạn hay không. 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ột mã truy cập mà Google sẽ dùng để truy cập vào API của bạn. Mã truy cập có thể là bất kỳ giá trị chuỗi nào, nhưng mã đó phải đại diện riêng cho người dùng và máy khách có mã thông báo và không được đoán được.

4. Gửi phản hồi HTTP chuyển hướng trình duyệt của người dùng đến URL do tham số redirect_uri chỉ định. Đưa mọi tham số sau đây vào phân đoạn URL:

   • access_token: mã truy cập bạn vừa tạo
   • token_type: chuỗi bearer
   • state: giá trị trạng thái chưa sửa đổi từ yêu cầu ban đầu Sau đây là ví dụ về URL kết quả:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Trình xử lý chuyển hướng OAuth 2.0 của Google sẽ nhận được mã truy cập và xác nhận rằng giá trị state vẫn không thay đổi. Sau khi có được mã truy cập cho dịch vụ của bạn, Google sẽ đính kèm mã truy cập này vào các lệnh gọi tiếp theo vào Hành động của bạn trong AppRequest.

Thiết kế giao diện người dùng bằng giọng nói cho quy trình xác thực

Nhắc nhở: Đừng cung cấp cho người dùng lời nhắc liên kết tài khoản bắt buộc khi bắt đầu cuộc trò chuyện với Hành động của bạn. Thay vào đó, hãy cung cấp cho người dùng chưa được xác thực một luồng khách để cho biết cách hoạt động của Hành động, sau đó chỉ yêu cầu liên kết tài khoản nếu cần thiết để tiếp tục. Nếu người dùng thường xuyên rời khỏi Hành động do các vấn đề liên kết tài khoản, thì Google sẽ không chủ động quảng bá Hành động đó. Điều này có thể làm giảm lưu lượng truy cập người dùng của Hành động đó.

Lưu ý: Bạn phải sử dụng Trình tạo hành động để tạo Hành động triển khai liên kết tài khoản.

Kiểm tra xem người dùng đã được xác minh hay chưa và bắt đầu quy trình liên kết tài khoản

1. Mở dự án Trình tạo hành động trong Bảng điều khiển Actions.
2. Tạo một cảnh mới để bắt đầu liên kết tài khoản trong Hành động của bạn:
   1. Nhấp vào Cảnh.
   2. Nhấp vào biểu tượng thêm (+) để thêm một cảnh mới.
3. Trong cảnh mới tạo, hãy nhấp vào biểu tượng thêm cho Điều kiện.
4. Thêm một điều kiện kiểm tra xem người dùng liên kết với cuộc trò chuyện có phải là người dùng đã xác minh hay không. Nếu quy trình kiểm tra không thành công, thì Hành động của bạn không thể thực hiện liên kết tài khoản trong cuộc trò chuyện và nên quay lại cung cấp quyền truy cập vào chức năng không yêu cầu liên kết tài khoản.
   1. Trong trường Enter new expression trong phần Điều kiện, hãy nhập logic sau: user.verificationStatus != "VERIFIED"
   2. Trong Chuyển đổi, hãy chọn một cảnh không yêu cầu liên kết tài khoản hoặc một cảnh là điểm truy cập vào chức năng chỉ dành cho khách.

1. Nhấp vào biểu tượng thêm cho Điều kiện.
2. Thêm điều kiện để kích hoạt quy trình liên kết tài khoản nếu người dùng không có danh tính được liên kết.
   1. Trong trường Enter new expression trong phần Điều kiện, hãy nhập logic sau: user.verificationStatus == "VERIFIED"
   2. Trong Chuyển đổi, hãy chọn cảnh hệ thống Liên kết tài khoản.
   3. Nhấp vào Lưu.

Sau khi lưu, một cảnh hệ thống liên kết tài khoản mới có tên là <SceneName>_AccountLinking sẽ được thêm vào dự án của bạn.

Tuỳ chỉnh cảnh liên kết tài khoản

1. Trong Cảnh, hãy chọn cảnh hệ thống liên kết tài khoản.
2. Nhấp vào Gửi lời nhắc rồi thêm một câu ngắn để mô tả cho người dùng lý do Hành động đó cần truy cập vào danh tính của họ (ví dụ: "Để lưu lựa chọn ưu tiên của bạn").
3. Nhấp vào Lưu.

1. Trong mục Điều kiện, hãy nhấp vào Nếu người dùng hoàn tất thành công quá trình liên kết tài khoản.
2. Thiết lập cách quy trình diễn ra nếu người dùng đồng ý liên kết tài khoản của họ. Ví dụ: gọi webhook để xử lý mọi logic kinh doanh tuỳ chỉnh bắt buộc và chuyển đổi lại cảnh ban đầu.
3. Nhấp vào Lưu.

1. Trong mục Điều kiện, hãy nhấp vào Nếu người dùng huỷ hoặc huỷ quy trình liên kết tài khoản.
2. Thiết lập cách quy trình diễn ra nếu người dùng không đồng ý liên kết tài khoản của họ. Ví dụ: gửi thông báo xác nhận và chuyển hướng đến các cảnh cung cấp chức năng không yêu cầu liên kết tài khoản.
3. Nhấp vào Lưu.

1. Trong mục Điều kiện, hãy nhấp vào Nếu xảy ra lỗi hệ thống hoặc mạng.
2. Định cấu hình cách tiến hành của quy trình nếu quy trình liên kết tài khoản không thể hoàn tất do lỗi hệ thống hoặc mạng. Ví dụ: gửi thông báo xác nhận và chuyển hướng đến các cảnh cung cấp chức năng không yêu cầu liên kết tài khoản.
3. Nhấp vào Lưu.

Xử lý các yêu cầu truy cập dữ liệu

Nếu yêu cầu Trợ lý chứa mã truy cập, trước tiên, hãy kiểm tra để đảm bảo rằng mã truy cập này là hợp lệ (và chưa hết hạn), sau đó truy xuất tài khoản người dùng được liên kết từ cơ sở dữ liệu của bạn.