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.

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

Đị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.
  1. 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.

  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
}

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

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.