Xác thực và uỷ quyền là các cơ chế được 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 xác thực và hoạt động uỷ quyền đối với các ứng dụng trong Chat và các yêu cầu về API của Chat.
Tổng quan về quy trình
Sơ đồ dưới đây trình bày các bước xác thực cấp cao và uỷ quyền cho Google Chat:
![Các bước nâng cao để xác thực và uỷ quyền trong Google Chat](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/auth-process.png?authuser=1&hl=vi)
Định cấu hình một dự án trê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 trên Google Cloud. Trong dự án Google Cloud, bạn bật Chat API, đị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 Phát triển trên Google Workspace và Tạo ứng dụng Chat.
Call Chat API: Khi ứng dụng của bạn gọi hàm Chat API này 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 một tài khoản dịch vụ, thông tin đăng nhập sẽ được gửi dưới dạng 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 cách sử dụng xác thực của người dùng chưa được cấp, nó 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 phạm vi mà bạn chỉ định trong khi thiết lập 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 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 có cấp cho ứng dụng của bạn hay không quyền truy cập vào dữ liệu được yêu cầu. Việc xác thực bằng tài khoản dịch vụ không cần có sự đồng ý của người dùng.
Gửi yêu cầu được phê duyệt về tài nguyên: Nếu người dùng đồng ý với phạm vi uỷ quyền, ứng dụng của bạn sẽ nhóm thông tin đăng nhập và thông tin người dùng phê duyệt phạm vi 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 chứa danh sách phạm vi đã cấp. Nếu danh sách phạm vi được trả về hạn chế hơn phạm vi đã 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 các tài nguyên được yêu cầu: Ứng dụng của bạn dùng mã truy cập do Google cấp để 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 ứng dụng của bạn phải truy cập vào API Google Chat ngoài vòng đời của một mã truy cập duy nhất, nó có thể nhận được mã làm mới. Để biết thêm thông tin, hãy xem Sử dụng OAuth 2.0 để truy cập Google API.
Yêu cầu thêm tài nguyên: Nếu cần thêm quyền truy cập, ứng dụng sẽ yêu cầu người dùng để cấp các phạm vi mới, dẫn đến một yêu cầu mới về việc lấy mã truy cập (các 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 một cách không đồng bộ. Họ cũng có thể hoàn thành các thao tác thay mặt người dùng, chẳng hạn như tạo phòng Chat hoặc lấy danh sách những người trong một 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 đang xử lý một phản hồi.
Để gửi thông báo không đồng bộ hoặc thực hiện thao tác thay mặt 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 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ộ với sự kiện tương tác.
Các ứng dụng Google Chat 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 Chat, trong đó có:
- 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 của ứng dụng Chat lệnh dấu gạch chéo.
Sơ đồ dưới đây biểu thị trình tự yêu cầu-phản hồi giữa một Người dùng Chat và ứng dụng Chat:
![Các sự kiện tương tác trong ứng dụng Chat không cần được cho phép](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/auth-synchronous.png?authuser=1&hl=vi)
- Người dùng gửi tin nhắn đến ứng dụng Chat sau 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 lần tương tác với ứng dụng Chat sự kiện.
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 tạo yêu cầu đến API Chat, 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 truy cập vào 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 hàm API Chat để:
- Tạo phòng Chat riêng để điều tra và khắc phục ngừng dịch vụ.
- Thêm người khác vào phòng Chat.
- Đăng tin nhắn lên phòng Chat để cung cấp thông tin chi tiết về ngừng dịch vụ.
Sơ đồ dưới đây minh hoạ chuỗi thông báo không đồng bộ giữa Ứng dụng Chat và phòng Chat:
![Yêu cầu xác thực cho các thông báo không đồng bộ](https://developers-dot-devsite-v2-prod.appspot.com/static/workspace/chat/images/auth-asynchronous.png?authuser=1&hl=vi)
- Ứng dụng Chat tạo tin nhắn bằng cách gọi hàm
API Chat bằng
spaces.messages.create
phương thức, 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 xác thực của người dùng.
- Google Chat hiển thị tin nhắn của ứng dụng tới một Chat cụ thể .
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, cũng như đăng ký ứng dụng của bạn để bạn có thể xuất bản sau này.
Để 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 URI OAuth 2.0 chuỗi chứa tên ứng dụng trên Google Workspace, loại dữ liệu quyền truy cập và cấp truy cập.
Phạm vi không nhạy cảm
Mã phạm vi | 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. Cho quyền sử dụng mọi tính năng dành cho ứng dụng Chat. |
Phạm vi nhạy cảm
Mã phạm vi | 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 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.spaces
|
Xem hoặc chỉnh sửa 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 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 | 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 kết 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. Để thông tin khác, xem 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á thư, cũng như thêm, xem và xoá lượt bày tỏ cảm xúc 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ên cho biết độ nhạy của chúng, theo định nghĩa sau đây:
Không nhạy cảm—Các phạm vi này cung cấp phạm vi nhỏ nhất của và chỉ yêu cầu xác minh ứng dụng cơ bản. Để thông tin về yêu cầu này, hãy xem Các bước chuẩn bị để 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 của người dùng trên Google sau khi được người dùng đó cho phép. Cần có bạn phải thực hiện quy trình xác minh ứng dụng bổ sung. Để biết thông tin về vấn đề này hãy xem Các bước dành cho ứng dụng yêu cầu thông tin nhạy cảm các phạm vi.
Bị hạn chế – Các 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 Google và yêu cầu bạn thực hiện quy trình xác minh trong phạm vi bị hạn chế. Để thông tin về yêu cầu này, hãy xem bài viết Dịch vụ API của Google: Dữ liệu người dùng Chính sách và Yêu cầu bổ sung đối với API cụ thể Phạm vi. Xem thêm Các bước dành cho ứng dụng yêu cầu bị hạn chế các phạm vi.
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ó thể thêm các phạm vi đó của Google. Để 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 của Google.
Để tìm hiểu thêm về phạm vi của API Google Workspace, hãy xem Đị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
Ứng dụng trong Chat có thể xác thực và uỷ quyền theo 2 cách 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 hành động thay mặt người dùng. Phạm vi OAuth chỉ định dữ liệu và hành động được uỷ quyền.
Bằng việc 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 sử dụng thông tin xác thực tài khoản dịch vụ. Luôn uỷ quyền cho ứng dụng
sử dụng phạm vi uỷ quyền chat.bot
.
Khi quyết định loại thông tin đăng nhập nào cần sử dụng cho một yêu cầu API cụ thể, Xin lưu ý rằng một số phương pháp API chỉ hỗ trợ một loại chứng chỉ danh tính. 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 việc uỷ quyền ứng dụng, các phương thức chỉ trả về các 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ề 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
bằng việc uỷ quyền ứng dụng sẽ trả về giá trị
danh sách không gian chứa ứng dụng. Đang gọi ListSpaces
bằng người dùng
uỷ quyền sẽ trả về danh sách không gian có người dùng. Ngang bằng
ứng dụng của bạn có thể sử dụng cả hai loại ủy quyền khi gọi phương thức
API Chat, 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à các phương thức được hỗ trợ phạm vi uỷ quyền:
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 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:
|
||
Cập nhật gói hội 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:
|
||
Truyền thông 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 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,
bạn phải dùng một phạm vi dựa trên
loại sự kiện:
|
||
Liệt kê các sự kiện của không gian | — |
Với Xác thực người dùng,
bạn phải sử dụng phạm vi cho mỗi
loại sự kiện có trong yêu cầu:
|
Đố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, xem Tìm hiểu về việc 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, vui lòng xem 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 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 Sử dụng OAuth 2.0 để truy cập Google API.
- 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ụ.