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 Loại liên kết, hãy chọn OAuth và Mã uỷ quyề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.
   • Ghi lại giá trị của Mã ứng dụng khách do Google cấp cho Hành động của bạn;
   • 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 và khoá bí mật dưới dạng chuỗi được 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) rồi đánh dấu vào hộp Google to truyền clientID và bí mật qua tiêu đề xác thực cơ bản HTTP.

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

Triển khai máy chủ OAuth

Quá trình triển khai luồng mã uỷ quyền bằng máy chủ OAuth 2.0 bao gồm 2 điểm cuối mà dịch vụ của bạn cung cấp qua HTTPS. Điểm cuối đầu tiên là điểm cuối uỷ quyền, chịu trách nhiệm tìm hoặc 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 sẽ hiển thị một giao diện người dùng đã đăng nhập cho những người dùng chưa đăng nhập và ghi lại sự đồng ý cho quyền truy cập được yêu cầu. Điểm cuối thứ hai là điểm cuối trao đổi mã thông báo, dùng để lấy các chuỗi đã mã hoá (gọi là mã thông báo) cho phép người dùng Hành động truy cập vào dịch vụ của bạn.

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

Phiên luồng mã xác thực OAuth 2.0 do Google khởi tạo có quy trình sau:

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. Nếu quy trình bắt đầu trên một thiết bị chỉ có giọng nói cho một Hành động, thì Google sẽ chuyển quá trình thực thi sang điện thoại.

2. 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.

   Lưu ý: Bạn phải thông báo rằng tài khoản của người dùng đang được liên kết với Google chứ không phải với một sản phẩm cụ thể của Google, chẳng hạn như Google Home hoặc Trợ lý Google.

3. Dịch vụ của bạn sẽ tạo một mã uỷ quyền và trả lại cho Google bằng cách chuyển hướng trình duyệt của người dùng về lại Google kèm theo mã uỷ quyền được đính kèm với yêu cầu.

4. Google gửi mã uỷ quyền đến điểm cuối trao đổi mã thông báo để xác minh tính xác thực của mã và trả về một mã truy cập và một mã làm mới. Mã truy cập là một mã thông báo ngắn hạn mà dịch vụ của bạn chấp nhận làm thông tin xác thực để truy cập vào API. Mã làm mới là một mã thông báo tồn tại lâu dài mà Google có thể lưu trữ và sử dụng để lấy mã truy cập mới khi hết hạn.

5. Sau khi người dùng hoàn tất quy trình liên kết tài khoản, mỗi yêu cầu tiếp theo mà Trợ lý gửi đến webhook thực hiện đơn hàng đều chứa một mã truy cập.

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 quy trình mã uỷ quyền OAuth 2.0, Google sẽ đưa người dùng đến điểm cuối uỷ 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 Google mà bạn đã đăng ký với 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.
scope	Không bắt buộc: Một tập hợp chuỗi phạm vi được phân tách bằng dấu cách chỉ định dữ liệu mà Google đang yêu cầu uỷ quyền.
response_type	Chuỗi code.

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&scope=REQUESTED_SCOPES&response_type=code

Để đ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 rằng client_id khớp với mã ứng dụng khách Google mà bạn đã đăng ký với Google, và redirect_uri khớp với URL chuyển hướng do Google cung cấp cho dịch vụ của bạn. Việc kiểm tra này rất quan trọng để ngăn chặn việc cấp quyền truy cập vào ứng dụng khách ngoài ý muốn hoặc được định cấu hình sai.

   Nếu bạn hỗ trợ nhiều quy trình OAuth 2.0, hãy xác nhận rằng response_type là code.

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ã uỷ quyền mà Google sẽ dùng để truy cập vào API của bạn. Mã uỷ quyền có thể là giá trị chuỗi bất kỳ, nhưng mã phải đại diện duy nhất cho người dùng, khách hàng có mã thông báo và thời gian hết hạn của mã đó, đồng thời không được đoán được. Bạn thường cấp mã uỷ quyền sẽ hết hạn sau khoảng 10 phút.

4. 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.

5. Chuyển hướng trình duyệt của người dùng đến URL do tham số redirect_uri chỉ định. Bao gồm mã uỷ quyền bạn vừa tạo và giá trị trạng thái ban đầu chưa sửa đổi khi bạn chuyển hướng bằng cách thêm các thông số code và state. Sau đây là ví dụ về URL kết quả:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Xử lý yêu cầu trao đổi mã thông báo

Điểm cuối trao đổi mã thông báo của dịch vụ của bạn chịu trách nhiệm về hai kiểu trao đổi mã thông báo:

• Đổi mã uỷ quyền lấy mã thông báo truy cập và mã làm mới
• Trao đổi mã thông báo làm mới để lấy mã truy cập

Yêu cầu trao đổi mã thông báo bao gồm các tham số sau:

Tham số điểm cuối trao đổi mã thông báo
client_id	Một chuỗi xác định nguồn gốc của yêu cầu là Google. Chuỗi này phải được đăng ký trong hệ thống của bạn làm giá trị nhận dạng duy nhất của Google.
client_secret	Chuỗi bí mật mà bạn đã đăng ký với Google cho dịch vụ của mình.
grant_type	Loại mã thông báo đang được trao đổi. authorization_code hoặc refresh_token.
code	Khi grant_type=authorization_code, mã mà Google nhận được từ điểm cuối của hoạt động đăng nhập hoặc trao đổi mã thông báo.
redirect_uri	Khi grant_type=authorization_code, tham số này sẽ là URL được dùng trong yêu cầu uỷ quyền ban đầu.
refresh_token	Khi grant_type=refresh_token, mã làm mới mà Google nhận được từ điểm cuối trao đổi mã thông báo của bạn.

Đổi mã uỷ quyền lấy mã thông báo truy cập và mã làm mới

Sau khi người dùng đăng nhập và điểm cuối uỷ quyền trả về một mã uỷ quyền ngắn hạn cho Google, Google sẽ gửi yêu cầu đến điểm cuối trao đổi mã thông báo của bạn để trao đổi mã uỷ quyền lấy mã truy cập và mã làm mới.

Đối với các yêu cầu này, giá trị của grant_type là authorization_code và giá trị của code là giá trị của mã uỷ quyền bạn đã cấp cho Google trước đây. Sau đây là ví dụ về yêu cầu trao đổi mã uỷ quyền lấy mã truy cập và mã làm mới:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

Để trao đổi mã uỷ quyền lấy mã truy cập và mã làm mới, điểm cuối trao đổi mã thông báo của bạn sẽ phản hồi các yêu cầu POST thực thi các bước sau:

1. Xác minh rằng client_id xác định nguồn gốc yêu cầu là nguồn gốc được uỷ quyền và client_secret khớp với giá trị dự kiến.
2. Xác minh những yếu tố sau:
   • Mã uỷ quyền hợp lệ và chưa hết hạn. Mã ứng dụng khách được chỉ định trong yêu cầu khớp với mã ứng dụng khách liên kết với mã uỷ quyền.
   • URL do tham số redirect_uri chỉ định giống hệt với giá trị dùng trong yêu cầu uỷ quyền ban đầu.
3. Nếu bạn không xác minh được tất cả các tiêu chí trên, hãy trả về lỗi HTTP 400 Bad Request với {"error": "invalid_grant"} là phần nội dung.
4. Nếu không, hãy tạo mã làm mới và mã truy cập bằng mã nhận dạng người dùng trong mã uỷ quyền. Các mã thông báo này có thể là giá trị chuỗi bất kỳ, nhưng phải đại diện duy nhất cho người dùng và khách hàng của mã thông báo, đồng thời không được đoán được. Đối với mã truy cập, bạn cũng cần ghi lại thời gian hết hạn của mã thông báo (thường là một giờ sau khi bạn cấp mã thông báo). Mã làm mới không hết hạn.
5. Trả về đối tượng JSON sau trong phần nội dung của phản hồi HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }
   

Google lưu trữ mã truy cập và mã làm mới cho người dùng, đồng thời ghi lại thời gian hết hạn của mã truy cập. Khi mã truy cập hết hạn, Google sẽ sử dụng mã thông báo làm mới để nhận mã truy cập mới từ điểm cuối trao đổi mã thông báo của bạn.

Trao đổi mã thông báo làm mới để lấy mã truy cập

Khi mã thông báo truy cập hết hạn, Google sẽ gửi yêu cầu đến điểm cuối trao đổi mã thông báo của bạn để trao đổi mã làm mới lấy mã truy cập mới.

Đối với các yêu cầu này, giá trị của grant_type là refresh_token và giá trị của refresh_token là giá trị của mã làm mới mà bạn đã cấp cho Google trước đây. Sau đây là ví dụ về yêu cầu trao đổi mã làm mới để lấy mã truy cập:

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

Để trao đổi mã làm mới lấy mã truy cập, điểm cuối trao đổi mã thông báo của bạn sẽ phản hồi các yêu cầu POST thực thi các bước sau:

1. Xác minh rằng client_id xác định nguồn gốc yêu cầu là Google và client_secret khớp với giá trị dự kiến.
2. Xác minh rằng mã làm mới là hợp lệ và mã ứng dụng khách được chỉ định trong yêu cầu khớp với mã ứng dụng khách liên kết với mã làm mới.
3. Nếu bạn không xác minh được tất cả các tiêu chí trên, hãy trả về lỗi HTTP 400 Bad Request với {"error": "invalid_grant"} là phần nội dung.
4. Nếu không, hãy sử dụng mã nhận dạng người dùng trong mã làm mới để tạo mã truy cập. Các mã thông báo này có thể là giá trị chuỗi bất kỳ, nhưng phải đại diện duy nhất cho người dùng và máy khách có mã thông báo và không được đoán được. Đối với mã truy cập, bạn cũng cần ghi lại thời gian hết hạn của mã thông báo (thường là một giờ sau khi bạn cấp mã thông báo).
5. Trả về đối tượng JSON sau trong phần nội dung của phản hồi HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Lưu ý: Bạn có thể tuỳ ý trả về một refresh_token mới trong câu trả lời của mình. Để biết thêm thông tin về thời điểm ưu tiên trả về một refresh_token mới, hãy xem bài viết Làm việc với mã thông báo.

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.