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