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

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

2. Người dùng này đăng nhập (nếu chưa đăng nhập) và cấp cho Google quyền truy cập 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 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 rồi trả lại mã này cho Google bằng cách chuyển hướng trình duyệt của người dùng quay lại Google bằng mã uỷ quyền được đính kèm vào yêu cầu.

4. Google sẽ gửi mã uỷ quyền đến điểm cuối trao đổi mã thông báo của bạn. Điểm cuối này xác minh tính xác thực của mã và trả về mã truy cập cũng như mã làm mới. Mã truy cập là một mã ngắn hạn mà dịch vụ của bạn chấp nhận làm thông tin đăng nhập để truy cập các API. Mã làm mới là mã tồn tại trong một thời gian dài mã thông báo mà Google có thể lưu trữ và sử dụng để thu nạp 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 gửi từ Trợ lý đến webhook thực hiện đơn hàng của bạn chứa mã truy cập.

Xử lý 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 qua mã uỷ quyền OAuth 2.0 quy trình này, Google sẽ chuyển người dùng đến điểm cuối uỷ quyền của bạn kèm theo yêu cầu bao gồm các thông số sau:

Tham số điểm cuối ủy 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 tới yêu cầu này.
state	Giá trị sổ sách được chuyển lại cho Google không thay đổi trong URI chuyển hướng.
scope	Không bắt buộc: Tập hợp các 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ó tại https://myservice.example.com/auth, một 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 của bạn có thể 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 của Google mà bạn đã đăng ký 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. Đây là những bước kiểm tra 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 bị đị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 đã đăng nhập vào dịch vụ của bạn chưa. Nếu người dùng chưa đăng nhập, 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à bất kỳ giá trị chuỗi nào, nhưng phải là duy nhất đại diện cho người dùng, máy khách và thời gian hết hạn của mã và thông tin đó không phải ai cũng đoán được. Bạn thường cấp phép các mã sẽ hết hạn sau khoảng 10 phút.

4. Xác nhận rằng URL được chỉ định bởi tham số redirect_uri có dạng như sau:

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

   YOUR_PROJECT_ID là mã nhận dạng có 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 tới URL được chỉ định Tham số redirect_uri. Bao gồm mã uỷ quyền mà bạn vừa được 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 tham số code và state. Sau đây là ví dụ của URL kết quả:

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

Xử lý các 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ề 2 loại mã thông báo sàn giao dịch:

• Trao đổi mã uỷ quyền để lấy mã truy cập và mã làm mới
• Mã làm mới trao đổi cho 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 dưới dạng mã 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 bạn.
grant_type	Loại mã thông báo đang được trao đổi. Một trong hai authorization_code hoặc refresh_token.
code	Khi grant_type=authorization_code, mã Google nhận được từ điểm cuối đăng nhập hoặc điểm cuối trao đổi mã thông báo.
redirect_uri	Khi grant_type=authorization_code, tham số này sẽ là URL dùng trong yêu cầu uỷ quyền ban đầu.
refresh_token	Khi grant_type=refresh_token, mã làm mới Google nhận được từ đ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

Sau khi người dùng đăng nhập và điểm cuối uỷ quyền của bạn sẽ trả về một yêu cầu uỷ quyền ngắn hạn mã đến 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 cho một mã truy cập và một 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ị code là giá trị của mã uỷ quyền mà trước đó bạn đã cấp cho Google. Sau đây là ví dụ về yêu cầu trao đổi mã uỷ quyền lấy một 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

Để đổ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 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 của yêu cầu là nguồn được uỷ quyền. và client_secret khớp với giá trị dự kiến.
2. Xác minh những thông tin sau:
   • Mã uỷ quyền hợp lệ và chưa hết hạn, đồng thời, ứng dụng Mã nhận dạng được chỉ định trong yêu cầu khớp với mã ứng dụng khách được liên kết với mã uỷ quyền.
   • URL do tham số redirect_uri chỉ định giống hệt nhau thành giá trị được sử dụng trong yêu cầu uỷ quyền ban đầu.
3. Nếu bạn không thể xác minh tất cả các tiêu chí trên, hãy trả về một HTTP 400 Lỗi Yêu cầu không hợp lệ, trong đó {"error": "invalid_grant"} là phần nội dung.
4. Nếu không, hãy tạo một quy trình làm mới bằng cách sử dụng mã nhận dạng người dùng trong mã uỷ quyền và 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à khách hàng mà mã thông báo dành cho họ, đồng thời không được có thể đoán được. Đối với mã truy cập, hãy ghi lại cả thời gian hết hạn của mã đó (thường là một giờ sau khi bạn phát hành mã thông báo). Mã làm mới không hết hạn.
5. Trả về đối tượng JSON sau đây 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 của mã truy cập đã hết hạn. Khi mã truy cập hết hạn, Google sẽ sử dụng quy trình làm mới để nhận mã truy cập mới từ điểm cuối trao đổi mã thông báo.

Mã làm mới trao đổi cho mã truy cập

Khi mã 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 để đổ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ị refresh_token là giá trị của mã làm mới mà bạn đã cấp trước đó cho Google. Sau đây là ví dụ về yêu cầu trao đổi mã làm mới cho một 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

Để đổ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 phản hồi POST yêu cầu thực thi các bước sau:

1. Xác minh rằng client_id xác định nguồn gốc của yêu cầu là Google và client_secret khớp với giá trị dự kiến giá trị.
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 thể xác minh tất cả các tiêu chí trên, hãy trả về một HTTP 400 Lỗi Yêu cầu không hợp lệ, trong đó {"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 từ mã làm mới để tạo quyền truy cập mã thông báo. Các mã thông báo này có thể là giá trị chuỗi bất kỳ, nhưng phải thể hiện riêng từng mã mã thông báo cho người dùng và máy khách, đồng thời các mã này không được đoán được. Đối với mã truy cập, hãy ghi lại cả thời gian hết hạn của mã đó (thường là một giờ sau khi bạn phát hành mã thông báo).
5. Trả về đối tượng JSON sau trong phần nội dung của HTTPS trả lời:

   {
   "token_type": "Người mang",
   "access_token": "ACCESS_TOKEN",
   "expiry_in" (hết hạn): SECONDS_TO_EXPIRATION
   }

Lưu ý: Bạn có thể trả về một refresh_token mới (không bắt buộc) trong câu trả lời của mình. Cho 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 Xử lý 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.