Xác thực và uỷ quyền là các cơ chế dùng để xác minh danh tính và quyền truy cập vào các tài nguyên tương ứng. Tài liệu này trình bày cách hoạt động của tính năng xác thực và uỷ quyền đối với ứng dụng Chat và yêu cầu API Chat.
Tổng quan về quy trình
Sơ đồ dưới đây cho thấy các bước xác thực và uỷ quyền cấp cao cho Google Chat:
Định cấu hình một dự án Google Cloud, bật API Chat và định cấu hình ứng dụng Chat: Trong quá trình phát triển, bạn tạo một dự án Google Cloud. Trong dự án Google Cloud, bạn cần bật API Chat, định cấu hình ứng dụng Chat và thiết lập tính năng xác thực. Để biết thêm thông tin, hãy xem các bài viết Phát triển trên Google Workspace và Tạo ứng dụng Chat.
Gọi API Chat: Khi gọi API Chat, ứng dụng sẽ gửi thông tin xác thực đến API Chat. Nếu ứng dụng của bạn xác thực bằng tài khoản dịch vụ, thì thông tin xác thực sẽ được gửi trong mã của ứng dụng. Nếu yêu cầu gọi API Chat bằng phương thức xác thực của người dùng chưa được cấp, thì ứng dụng sẽ nhắc người dùng đăng nhập.
Yêu cầu tài nguyên: Ứng dụng của bạn yêu cầu quyền truy cập thông qua các phạm vi mà bạn chỉ định trong khi thiết lập tính năng xác thực.
Yêu cầu sự đồng ý: Nếu ứng dụng của bạn đang xác thực với tư cách người dùng, Google sẽ hiển thị màn hình xin phép bằng OAuth để người dùng có thể quyết định có cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu được yêu cầu hay không. Việc xác thực bằng tài khoản dịch vụ không yêu cầu sự đồng ý của người dùng.
Gửi yêu cầu cấp tài nguyên đã được phê duyệt: Nếu người dùng đồng ý với các phạm vi uỷ quyền, ứng dụng sẽ gói thông tin xác thực và các phạm vi được người dùng phê duyệt vào một yêu cầu. Yêu cầu được gửi đến máy chủ uỷ quyền của Google để lấy mã truy cập.
Google trả về một mã truy cập: Mã truy cập này chứa danh sách các phạm vi đã cấp. Nếu danh sách các phạm vi được trả về hạn chế hơn phạm vi yêu cầu, ứng dụng sẽ tắt mọi tính năng bị mã thông báo giới hạn.
Quyền truy cập vào tài nguyên được yêu cầu: Ứng dụng của bạn sử dụng mã truy cập của Google để gọi API Chat và truy cập vào các tài nguyên của API Chat.
Lấy mã làm mới (không bắt buộc): Nếu phải truy cập vào API Google Chat sau thời gian tồn tại của một mã truy cập, ứng dụng của bạn có thể nhận được mã làm mới. Để biết thêm thông tin, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập API Google.
Yêu cầu thêm tài nguyên: Nếu cần thêm quyền truy cập, ứng dụng của bạn sẽ yêu cầu người dùng cấp phạm vi mới, dẫn đến một yêu cầu mới để nhận mã truy cập (bước 3-6).
Khi các ứng dụng trong Chat yêu cầu xác thực
Các ứng dụng trong Chat có thể gửi tin nhắn để phản hồi một hoạt động tương tác của người dùng hoặc gửi không đồng bộ. Họ cũng có thể thay mặt người dùng hoàn thành các thao tác, chẳng hạn như tạo phòng Chat hoặc xem danh sách người tham gia trong phòng Chat.
Các ứng dụng nhắn tin không yêu cầu xác thực để phản hồi hoạt động tương tác của người dùng, trừ phi ứng dụng Chat gọi API Chat hoặc một API khác của Google trong khi xử lý câu trả lời.
Để gửi tin nhắn không đồng bộ hoặc thực hiện thao tác thay cho người dùng, các ứng dụng trong Chat gửi yêu cầu RESTful đến API Chat. Yêu cầu này cần phải được xác thực và uỷ quyền.
Phản hồi hoạt động tương tác của người dùng không yêu cầu xác thực
Các ứng dụng Google Chat không cần xác thực với tư cách người dùng hoặc ứng dụng Chat để nhận và phản hồi đồng bộ với các sự kiện tương tác.
Các ứng dụng Google Chat sẽ nhận được sự kiện tương tác bất cứ khi nào người dùng tương tác hoặc gọi một ứng dụng, bao gồm:
- Người dùng gửi tin nhắn cho ứng dụng nhắn tin.
- Một người dùng đề cập đến một ứng dụng trong Chat bằng @.
- Người dùng gọi một trong các lệnh dấu gạch chéo của ứng dụng Chat.
Sơ đồ dưới đây cho thấy trình tự phản hồi giữa một người dùng Chat và ứng dụng Chat:
- Người dùng gửi tin nhắn cho ứng dụng Chat trong Google Chat.
- Google Chat sẽ chuyển tiếp tin nhắn đến ứng dụng.
- Ứng dụng nhận tin nhắn, xử lý tin nhắn và trả về nội dung phản hồi cho Google Chat.
- Google Chat hiển thị câu trả lời cho người dùng hoặc trong một không gian.
Trình tự này lặp lại cho mỗi sự kiện tương tác với ứng dụng Chat.
Thư không đồng bộ yêu cầu xác thực
Tin nhắn không đồng bộ xảy ra khi ứng dụng Chat gửi yêu cầu đến API Chat, yêu cầu này đòi hỏi phải xác thực và uỷ quyền.
Khi gọi API Chat, các ứng dụng trong Chat có thể đăng tin nhắn lên Google Chat hoặc hoàn thành công việc và truy cập vào dữ liệu thay mặt người dùng. Ví dụ: sau khi phát hiện sự cố máy chủ ngừng hoạt động, ứng dụng Chat có thể gọi API Chat để:
- Tạo một phòng Chat chuyên kiểm tra và khắc phục sự cố ngừng dịch vụ.
- Thêm người khác vào phòng Chat.
- Hãy đăng tin nhắn vào phòng Chat để cung cấp thông tin chi tiết về việc ngừng dịch vụ.
Sơ đồ dưới đây cho thấy trình tự tin nhắn không đồng bộ giữa một ứng dụng trong Chat và một phòng Chat:
- Ứng dụng Chat tạo tin nhắn bằng cách gọi API Chat thông qua phương thức
spaces.messages.create
và đưa thông tin đăng nhập của người dùng vào yêu cầu HTTP. - Google Chat xác thực ứng dụng Chat bằng tài khoản dịch vụ hoặc thông tin đăng nhập của người dùng.
- Google Chat hiển thị tin nhắn của ứng dụng đến một phòng Chat được chỉ định.
Phạm vi API Chat
Định cấu hình màn hình xin phép bằng OAuth và chọn phạm vi để xác định thông tin nào sẽ hiển thị cho người dùng và người đánh giá ứng dụng, đồng thời đăng ký ứng dụng của bạn để bạn có thể phát hành sau.
Để xác định cấp truy cập được cấp cho ứng dụng của mình, bạn cần xác định và khai báo phạm vi cấp quyền. Phạm vi uỷ quyền là một chuỗi URI OAuth 2.0 có chứa tên ứng dụng trên Google Workspace, loại dữ liệu mà ứng dụng này truy cập và cấp truy cập.
Phạm vi không nhạy cảm
Mã phạm vi | Nội dung mô tả |
---|---|
https://www.googleapis.com/auth/chat.bot
|
Phạm vi Cho phép các ứng dụng trong Chat xem cuộc trò chuyện và gửi tin nhắn. Cấp quyền truy cập vào tất cả tính năng có trong các ứng dụng trong Chat. |
Phạm vi nhạy cảm
Mã phạm vi | Nội dung mô tả |
---|---|
https://www.googleapis.com/auth/chat.spaces
|
Tạo cuộc trò chuyện và không gian cũng như xem hoặc cập nhật siêu dữ liệu (bao gồm cả chế độ cài đặt nhật ký) trong Chat. |
https://www.googleapis.com/auth/chat.spaces.create
|
Tạo cuộc trò chuyện mới trong Chat. |
https://www.googleapis.com/auth/chat.spaces.readonly
|
Xem cuộc trò chuyện và các không gian trong ứng dụng Chat. |
https://www.googleapis.com/auth/chat.memberships
|
Xem, thêm và xoá thành viên khỏi các cuộc trò chuyện trong ứng dụng Chat. |
https://www.googleapis.com/auth/chat.memberships.app
|
Thêm và xoá chính ứng dụng khỏi các cuộc trò chuyện trong Google Chat. |
https://www.googleapis.com/auth/chat.memberships.readonly
|
Xem thành viên trong các cuộc trò chuyện trên Chat. |
https://www.googleapis.com/auth/chat.messages.create
|
Soạn và gửi tin nhắn trong Chat. |
https://www.googleapis.com/auth/chat.messages.reactions
|
Xem, thêm và xoá lượt thể hiện cảm xúc đối với tin nhắn trong Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.create
|
Thêm biểu tượng cảm xúc vào một tin nhắn trong Chat. |
https://www.googleapis.com/auth/chat.messages.reactions.readonly
|
Xem các lượt thể hiện cảm xúc đối với tin nhắn trong Chat. |
https://www.googleapis.com/auth/chat.users.readstate
|
Xem và sửa đổi dấu thời gian đọc lần gần đây nhất của cuộc trò chuyện trên Chat. |
https://www.googleapis.com/auth/chat.users.readstate.readonly
|
Xem thời gian đọc gần đây nhất của cuộc trò chuyện trên Chat. |
Phạm vi bị hạn chế
Mã phạm vi | Nội dung mô tả |
---|---|
https://www.googleapis.com/auth/chat.delete
|
Xoá các cuộc trò chuyện và không gian, đồng thời xoá quyền truy cập vào các tệp liên kết trong Chat. |
https://www.googleapis.com/auth/chat.import
|
Nhập không gian, tin nhắn và gói thành viên vào Chat. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat nhập dữ liệu |
https://www.googleapis.com/auth/chat.messages
|
Xem, soạn, gửi, cập nhật và xoá tin nhắn cũng như thêm, xem và xoá biểu tượng cảm xúc đối với tin nhắn. |
https://www.googleapis.com/auth/chat.messages.readonly
|
Xem tin nhắn và lượt thể hiện cảm xúc trong Chat. |
Các phạm vi trong các bảng trước đó biểu thị mức độ nhạy cảm của các yếu tố này, theo các định nghĩa sau:
Không nhạy cảm: Những phạm vi này cung cấp phạm vi uỷ quyền nhỏ nhất và chỉ yêu cầu xác minh ứng dụng cơ bản. Để biết thông tin về yêu cầu này, hãy xem bài viết Các bước chuẩn bị xác minh.
Nhạy cảm—Các phạm vi này cho phép ứng dụng của bạn truy cập vào dữ liệu trên Google của một người dùng cụ thể sau khi được người dùng đó cho phép. Phương thức này yêu cầu bạn trải qua quy trình xác minh ứng dụng bổ sung. Để biết thông tin về yêu cầu này, hãy xem bài viết Các bước dành cho ứng dụng yêu cầu phạm vi nhạy cảm.
Bị hạn chế – Những phạm vi này cung cấp quyền truy cập rộng rãi vào dữ liệu người dùng trên Google và yêu cầu bạn phải thực hiện quy trình xác minh phạm vi bị hạn chế. Để biết thông tin về yêu cầu này, hãy xem Dịch vụ API của Google: Chính sách dữ liệu người dùng và Yêu cầu bổ sung đối với các phạm vi API cụ thể. Xem thêm bài viết Các bước dành cho ứng dụng yêu cầu phạm vi bị hạn chế.
Nếu ứng dụng của bạn yêu cầu quyền truy cập vào bất kỳ API nào khác của Google, thì bạn cũng có thể thêm các phạm vi đó. Để biết thêm thông tin về các phạm vi API của Google, hãy xem phần Sử dụng OAuth 2.0 để truy cập API Google.
Để tìm hiểu thêm về phạm vi cho API Google Workspace, hãy xem bài viết Định cấu hình màn hình xin phép bằng OAuth và chọn phạm vi.
Loại xác thực bắt buộc
Có hai cách để ứng dụng trong Chat xác thực và uỷ quyền bằng API Chat: thông tin đăng nhập của người dùng hoặc tài khoản dịch vụ.
Với tính năng uỷ quyền thông tin xác thực người dùng, ứng dụng Chat có thể truy cập vào dữ liệu người dùng và hoàn tất các thao tác thay cho người dùng. Phạm vi OAuth chỉ định dữ liệu và hành động được phép.
Với uỷ quyền cho ứng dụng, ứng dụng Chat sẽ truy cập vào API dưới dạng ứng dụng bằng thông tin đăng nhập tài khoản dịch vụ. Tính năng uỷ quyền ứng dụng luôn sử dụng phạm vi uỷ quyền chat.bot
.
Khi quyết định loại thông tin xác thực sẽ sử dụng cho một yêu cầu API cụ thể, hãy lưu ý rằng một số phương thức API chỉ hỗ trợ một loại thông tin xác thực cụ thể. Nếu một phương thức API hỗ trợ cả hai thông tin xác thực, thì loại thông tin xác thực dùng trong lệnh gọi sẽ ảnh hưởng đến kết quả được trả về:
- Với sự uỷ quyền cho ứng dụng, các phương thức này chỉ trả về những tài nguyên mà ứng dụng có thể truy cập.
- Khi được người dùng cho phép, các phương thức này chỉ trả về những tài nguyên mà người dùng có thể truy cập trong giao diện người dùng Chat.
Ví dụ: việc gọi phương thức ListSpaces
có uỷ quyền cho ứng dụng sẽ trả về danh sách không gian chứa thành phần của ứng dụng. Việc gọi ListSpaces
bằng lệnh uỷ quyền của người dùng sẽ trả về danh sách các không gian mà người dùng là thành viên. Trên thực tế, ứng dụng của bạn có thể sử dụng cả hai loại uỷ quyền khi gọi API Chat, tuỳ vào chức năng mà bạn muốn dùng.
Đối với các lệnh gọi API Chat không đồng bộ
Bảng sau đây liệt kê các phương thức API Chat và phạm vi uỷ quyền được hỗ trợ:
Phương thức | Hỗ trợ Xác thực người dùng | Hỗ trợ Xác thực ứng dụng | Phạm vi uỷ quyền được hỗ trợ | |
---|---|---|---|---|
Không gian | ||||
Tạo không gian | — |
Bằng cách Xác thực người dùng:
|
||
Thiết lập không gian | — |
Bằng cách Xác thực người dùng:
|
||
Mua không gian |
Bằng cách Xác thực người dùng:
|
|||
Không gian danh sách |
Bằng cách Xác thực người dùng:
|
|||
Cập nhật không gian | — |
Bằng cách Xác thực người dùng:
|
||
Xoá không gian | — |
Bằng cách Xác thực người dùng:
|
||
Hoàn tất quy trình nhập không gian | — |
Bằng cách Xác thực người dùng:
|
||
Tìm tin nhắn trực tiếp |
Bằng cách Xác thực người dùng:
|
|||
Thành viên | ||||
Tạo thành viên | — |
Bằng cách Xác thực người dùng:
|
||
Đăng ký hội viên |
Bằng cách Xác thực người dùng:
|
|||
Danh sách thành viên |
Bằng cách Xác thực người dùng:
|
|||
Xoá thành viên | — |
Bằng cách Xác thực người dùng:
|
||
Tin nhắn | ||||
Tạo thông báo |
Bằng cách Xác thực người dùng:
|
|||
Nhận thông báo |
Bằng cách Xác thực người dùng:
|
|||
Liệt kê các thông báo | — |
Bằng cách Xác thực người dùng:
|
||
Cập nhật thông báo |
Bằng cách Xác thực người dùng:
|
|||
Xoá tin nhắn |
Bằng cách Xác thực người dùng:
|
|||
Bày tỏ cảm xúc | ||||
Tạo biểu tượng cảm xúc | — |
Bằng cách Xác thực người dùng:
|
||
Liệt kê biểu tượng cảm xúc | — |
Bằng cách Xác thực người dùng:
|
||
Xoá một lượt thể hiện cảm xúc | — |
Bằng cách Xác thực người dùng:
|
||
Nội dung đa phương tiện và tệp đính kèm | ||||
Tải nội dung nghe nhìn lên dưới dạng tệp đính kèm | — |
Bằng cách Xác thực người dùng:
|
||
Tải nội dung nghe nhìn xuống |
Bằng cách Xác thực người dùng:
|
|||
Nhận tệp đính kèm cho tin nhắn | — |
Với Xác thực ứng dụng:
|
||
Trạng thái đọc của người dùng | ||||
Xem trạng thái đọc không gian của người dùng | — |
Bằng cách Xác thực người dùng:
|
||
Cập nhật trạng thái đọc không gian của người dùng | — |
Bằng cách Xác thực người dùng:
|
||
Nhận trạng thái đọc chuỗi thư của người dùng | — |
Bằng cách Xác thực người dùng:
|
||
Sự kiện không gian | ||||
Nhận sự kiện trong không gian | — |
Bằng cách Xác thực người dùng:
|
||
Liệt kê các sự kiện trong không gian | — |
Bằng cách Xác thực người dùng:
|
Đối với sự kiện tương tác với ứng dụng Chat
Bảng sau đây liệt kê những cách phổ biến mà người dùng tương tác với các ứng dụng trong Chat và việc xác thực là bắt buộc hay có hỗ trợ:
Trường hợp | Không yêu cầu xác thực | Hỗ trợ Xác thực người dùng | Hỗ trợ Xác thực ứng dụng | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Nhận tin nhắn từ: |
|
|||||||||||||||
Trả lời tin nhắn: |
|
|||||||||||||||
Gửi tin nhắn mới: |
|
Chủ đề có liên quan
- Để biết thông tin tổng quan về quy trình xác thực và uỷ quyền trong Google Workspace, hãy xem bài viết Tìm hiểu về quy trình xác thực và uỷ quyền.
- Để biết thông tin tổng quan về quy trình xác thực và uỷ quyền trong Google Cloud, hãy xem bài viết Tổng quan về quy trình xác thực.
- Để tìm hiểu thêm về tài khoản dịch vụ, hãy xem bài viết Tài khoản dịch vụ.
- Để tìm hiểu thêm về cách API Google tận dụng OAuth 2.0, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập API Google.
- Thiết lập phương thức xác thực và uỷ quyền bằng thông tin xác thực của người dùng hoặc tài khoản dịch vụ.