Loại liên kết OAuth hỗ trợ 2 quy trình OAuth 2.0 tiêu chuẩn ngành: quy trình ngầm ẩn và mã uỷ quyền. Trong quy trình mã ngầm ẩn, 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. Sau khi đăng nhập thành công, bạn sẽ trả về một mã truy cập dài hạn cho Google. Sau đó, mã truy cập này sẽ được đưa vào mọi yêu cầu mà Trợ lý gửi đến Hành động của bạn.
Liên kết OAuth là giải pháp liên kết tài khoản được đề xuất cho các trường hợp sau:
- Bạn hiện đã triển khai máy chủ OAuth 2.0 và không thể mở rộng điểm cuối trao đổi mã thông báo để thêm tính năng hỗ trợ cho các giao thức của Google nhằm liên kết tự động và tạo tài khoản từ mã thông báo mã nhận dạng (tức là thêm tham số
intent=getvàintent=createtrong yêu cầu đến điểm cuối này).
Để xác minh rằng liên kết OAuth là giải pháp phù hợp với bạn, hãy xem trang Chọn loại liên kết tài khoản.
Từ khóa
Trước khi bạn đọc về cách hoạt động của liên kết OAuth, hãy tự làm quen với các thuật ngữ sau:
user.verificationStatus: Một thuộc tính do hệ thống đặt để cho biết liệu phiên hiện tại có người dùng đã xác minh hay không.user.accountLinkingStatus: Một thuộc tính do hệ thống đặt để cho biết liệu người dùng trong phiên hiện tại có danh tính được liên kết hay không.Cảnh hệ thống liên kết tài khoản: Một cảnh được xác định trước, triển khai quy trình xác nhận cho việc liên kết tài khoản, và có thể được tuỳ chỉnh để phù hợp với các trường hợp sử dụng cụ thể.
Quy trình mã uỷ quyền: Trong quy trình OAuth 2.0 này, Google sẽ mở điểm cuối của việc uỷ quyền trong trình duyệt của người dùng. Nếu đăng nhập thành công, dịch vụ của bạn sẽ tạo một mã uỷ quyền và trả lại mã đó cho Google. Google gửi mã uỷ quyền này đến điểm cuối trao đổi mã thông báo của bạn. Điểm cuối này sẽ 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.
Quy trình này yêu cầu 2 điểm cuối:
- Điểm cuối uỷ quyền: Điểm cuối chịu trách nhiệm tìm kiế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 này thực hiện những việc sau:
- Hiển thị giao diện đăng nhập cho người dùng chưa đăng nhập.
- 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 trao đổi mã thông báo: Điểm cuối này 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. Điểm cuối này chịu trách nhiệm cho hai loại trao đổi:
- Trao đổi mã uỷ quyền lấy mã làm mới dài hạn và mã truy cập ngắn hạn. Quá trình trao đổi này xảy ra khi người dùng thực hiện quy trình liên kết tài khoản.
- Trao đổi mã thông báo làm mới dài hạn lấy một mã truy cập ngắn hạn. Quá trình trao đổi này xảy ra khi Google cần một mã truy cập mới vì mã này đã hết hạn.
- Điểm cuối uỷ quyền: Điểm cuối chịu trách nhiệm tìm kiế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 này thực hiện những việc sau:
Luồng mã ngầm ẩn: Trong quy trình OAuth 2.0 này, 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 đăng nhập thành công, bạn sẽ trả về một mã truy cập dài hạn cho Google. Sau đó, mã truy cập này sẽ được đưa vào mọi yêu cầu mà Trợ lý gửi đến Hành động của bạn. Quy trình này chỉ yêu cầu một điểm cuối uỷ quyền.
Mã truy cập: Mã thông báo cho phép dịch vụ của bạn truy cập vào các phần trong dữ liệu của người dùng. Mã truy cập được liên kết với từng người dùng riêng lẻ và phải không xác định được.
Mã thông báo làm mới: Mã thông báo được đổi lấy mã truy cập mới sau khi mã truy cập tồn tại trong một thời gian ngắn hết hạn.
Cách thức hoạt động
Phần này mô tả quy trình chung cho mã uỷ quyền OAuth và các luồng ngầm ẩn. Phần sau đây, Các quy trình liên kết OAuth, mô tả các quy trình khác nhau có thể xảy ra với OAuth.
Quy trình mã uỷ quyền có thể tóm tắt như sau:
- Hành động của bạn sẽ hỏi người dùng xem họ có muốn liên kết tài khoản của họ với dịch vụ của bạn hay không.
- Sau khi người dùng đồng ý liên kết các tài khoản, 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ỉ có giọng nói cho một Hành động, Google sẽ chuyển thực thi đó sang điện thoại.
- 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).
- 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.
- 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.
- 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 từ Trợ lý đến webhook thực hiện đơn hàng của bạn đều chứa một mã truy cập.
Quy trình mã ngầm ẩn có thể được tóm tắt như sau:
- Hành động của bạn sẽ hỏi người dùng xem họ có muốn liên kết tài khoản của họ với dịch vụ của bạn hay không.
- Sau khi người dùng đồng ý liên kết các tài khoản, 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).
- 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 quay lại Google bằng mã truy cập được đính kèm với yêu cầu.
- Sau khi người dùng hoàn tất quy trình liên kết tài khoản, Google sẽ gọi các API của dịch vụ và đính kèm mã truy cập vào mỗi yêu cầu. Dịch vụ của bạn 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.
Quy trình mã uỷ quyền cơ bản như sau:
- Hành động của bạn sẽ hỏi người dùng xem họ có muốn liên kết tài khoản của họ với dịch vụ của bạn hay không.
- Sau khi người dùng đồng ý liên kết các tài khoản, 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ỉ có giọng nói cho một Hành động, Google sẽ chuyển thực thi đó sang điện thoại.
- 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).
- Dịch vụ của bạn sẽ tạo một mã uỷ quyền rồi trả về cho Google bằng cách chuyển hướng trình duyệt của người dùng về lại Google bằng mã uỷ quyền ngắn hạn được đính kèm với yêu cầu.
- 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.
- 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 từ Trợ lý đến webhook thực hiện đơn hàng của bạn đều chứa một mã truy cập.
Quy trình liên kết OAuth
Phần này đề cập đến các quy trình khác nhau có thể xảy ra khi liên kết OAuth.
Mỗi luồng chứa các bước phổ biến sau đây sau khi người dùng gọi Hành động của bạn:
Trong quy trình trên, bạn sẽ chuyển sang cảnh hệ thống liên kết tài khoản và đưa ra lý do tuỳ chỉnh. Trợ lý sẽ hỏi người dùng xem họ có muốn liên kết tài khoản của họ với dịch vụ của bạn hay không và cho họ thấy một màn hình có các quyền được yêu cầu. Khi người dùng cho phép, Google sẽ chuyển hướng người dùng đến điểm cuối uỷ quyền của dịch vụ trong trình duyệt. Người dùng đăng nhập (hoặc tạo một tài khoản mới tuỳ thuộc vào cấu hình của bạn) và cấp cho Hành động của bạn quyền truy cập vào dữ liệu của họ.
Các luồng sau điểm này sẽ khác nhau tuỳ thuộc vào việc bạn có triển khai luồng ngầm ẩn hoặc luồng mã uỷ quyền hay không. Các quy trình này được mô tả trong các phần sau.
Luồng 1: Người dùng đăng nhập bằng luồng ngầm ẩn
Sau khi người dùng đăng nhập và thông tin xác thực của họ được xác minh, dịch vụ của bạn sẽ tạo một mã truy cập dài hạn và trả lại mã đó cho Google. Tại thời điểm này, danh tính của người dùng trong Hành động của bạn được liên kết với tài khoản mà họ đã đăng nhập, đồng thời mã truy cập sẽ được đính kèm vào mỗi lệnh gọi API mà Google thực hiện đến các API của dịch vụ.
Quy trình 2: Người dùng đăng nhập bằng quy trình mã uỷ quyền
Sau khi người dùng đăng nhập và thông tin xác thực của họ được xác minh, dịch vụ của bạn sẽ tạo một mã uỷ quyền và trả lại mã đó cho Google.
Mã uỷ quyền này được gửi đến điểm cuối trao đổi mã thông báo. Điểm cuối này sẽ trả về cả mã truy cập và mã làm mới. Tại thời điểm này, danh tính của người dùng trong Hành động của bạn được liên kết với bất kỳ tài khoản nào mà họ đã đăng nhập và mỗi yêu cầu tiếp theo được gửi từ Trợ lý đến phương thức thực hiện của bạn đều chứa một mã truy cập.