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 tài nguyên. 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ơ đồ sau đây cho thấy các bước tổng quan về việc xác thực và uỷ quyền cho Google Chat:
Đị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 sẽ bật Chat API, định cấu hình ứng dụng Chat và thiết lập quy trình 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, 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 yêu cầu người dùng đồng ý.
Gửi yêu cầu được phê duyệt cho 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ẽ gói thông tin xác thực và 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 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 đượ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 bởi 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 thời gian hoạt động 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
Ứng dụng trò chuyện có thể gửi tin nhắn để phản hồi hoạt động 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ể 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.
Ứng dụng trò chuyện 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 trò chuyện 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 các tác vụ, ứng dụng Chat sẽ tạo các yêu cầu RESTful đến Chat API. API này 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.
Ứng dụng Google Chat nhận được các sự kiện tương tác mỗi khi người dùng tương tác hoặc gọi một ứng dụng Chat, bao gồm:
- 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 Chat.
- 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:
- 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 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 Chat API để:
- 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:
- Ứng dụng Chat tạo tin nhắn bằng cách gọi hàm
API Chat bằng
spaces.messages.createphương thức, và đưa thông tin xác thực 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 tới một Chat cụ thể .
Phạm vi Chat API
Đị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, 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
|
Cho phép các ứng dụng trong Chat xem cuộc trò chuyện và gửi tin nhắn. Phạm vi này chỉ hỗ trợ xác thực ứng dụng bằng tài khoản dịch vụ. Bạn không thể xác thực bằng thông tin đăng nhập của người dùng hoặc bằng uỷ quyền trên toàn miền bằng phạm vi này. |
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á lượt thể hiện cảm xúc 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 bày tỏ cảm xúc 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 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. |
https://www.googleapis.com/auth/chat.app.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ý và chế độ cài đặt quyền truy cập) trong Chat. Cần sự phê duyệt của quản trị viên. Phạm vi này chỉ hỗ trợ xác thực ứng dụng với tài khoản dịch vụ. Bạn không thể xác thực bằng thông tin đăng nhập của người dùng hoặc bằng tính năng uỷ quyền trên toàn miền bằng phạm vi này. |
https://www.googleapis.com/auth/chat.app.spaces.create
|
Tạo cuộc trò chuyện và không gian mới trong Chat. Cần sự phê duyệt của quản trị viên. Phạm vi này chỉ hỗ trợ xác thực ứng dụng bằng tài khoản dịch vụ. Bạn không thể xác thực bằng thông tin đăng nhập của người dùng hoặc bằng tính năng uỷ quyền trên toàn miền bằng phạm vi này. |
https://www.googleapis.com/auth/chat.app.memberships
|
Xem, thêm, cập nhật và xoá thành viên khỏi các cuộc trò chuyện và không gian trong Chat. Yêu cầu phê duyệt của quản trị viên. Phạm vi này chỉ hỗ trợ xác thực ứng dụng với tài khoản dịch vụ. Bạn không thể xác thực bằng thông tin đăng nhập của người dùng hoặc bằng tính năng uỷ quyền trên toàn miền bằng phạm vi này. |
https://www.googleapis.com/auth/chat.customemojis
|
Xem, tạo và xoá biểu tượng cảm xúc tuỳ chỉnh 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. |
https://www.googleapis.com/auth/chat.app.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. Yêu cầu quản trị viên phê duyệt. Phạm vi này chỉ hỗ trợ xác thực ứng dụng bằng tài khoản dịch vụ. Bạn không thể xác thực bằng thông tin đăng nhập của người dùng hoặc bằng uỷ quyền trên toàn miền bằng phạm vi này. |
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 quyền truy cập uỷ quyền nhỏ nhất 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. Bạn cần phải thực hiện 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 phần Các bước cho ứng dụng yêu cầu phạm vi nhạy cảm.
Bị hạn chế—Các 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 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ế. Để 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à Các yêu cầu bổ sung đối với phạm vi API cụ thể. Xem thêm Các bước 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 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:
- Xác thực người dùng
- Xác thực người dùng cho phép ứng dụng Chat 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. Trừ phi ứng dụng Chat được quản trị viên cài đặt hoặc được uỷ quyền trên toàn miền, thì trong lần đầu tiên ứng dụng Chat thực hiện hành động thay mặt cho người dùng, người dùng phải uỷ quyền cho ứng dụng Chat bằng màn hình xin phép OAuth.
- Xác thực ứng dụng
Xác thực ứng dụng cho phép Thông tin đăng nhập và quyền truy cập vào tài khoản dịch vụ mà ứng dụng Chat sử dụng dữ liệu và hoàn tất hành động. Vì ứng dụng Chat sử dụng thông tin xác thực của riêng mình để truy cập và làm việc với các tài nguyên, người dùng cuối không cần phê duyệt Lệnh gọi API của ứng dụng Chat, và bạn không thể thêm phạm vi uỷ quyền OAuth hỗ trợ cho việc uỷ quyền ứng dụng vào màn hình xin phép bằng OAuth.
Hai loại phạm vi uỷ quyền OAuth hỗ trợ xác thực ứng dụng:
https://www.googleapis.com/auth/chat.bot: Ứng dụng Chat của bạn có thể gọi các phương thức API Google Chat hỗ trợ phạm vi uỷ quyền này để tạo, cập nhật, lấy, liệt kê hoặc xoá các tài nguyên mà ứng dụng có quyền truy cập, chẳng hạn như tin nhắn trong không gian mà người dùng cuối thêm ứng dụng Chat của bạn vào. Thông tin Ứng dụng Chat có thể tự cấp phạm vi uỷ quyền này, không cần có sự uỷ quyền của quản trị viên hoặc người dùng cuối.https://www.googleapis.com/auth/chat.app.*(Bản dùng thử dành cho nhà phát triển): Bạn cần được quản trị viên phê duyệt một lần để sử dụng các phạm vi này. Để nhận được phê duyệt của quản trị viên, bạn cần chuẩn bị tài khoản dịch vụ của ứng dụng Chat để nhận được phê duyệt của quản trị viên bằng cách tạo ứng dụng OAuth tương thích với Google Workspace Marketplace và định cấu hình ứng dụng trong SDK Google Workspace Marketplace. Các phạm vi này cho phép ứng dụng Chat của bạn gọi API Google Chat cụ thể . Ví dụ:chat.app.spaces.createcho phép các ứng dụng tạo Phòng Chat.
Nếu một phương thức hỗ trợ cả việc xác thực người dùng hoặc ứng dụng, thì API Chat sẽ trả về các kết quả khác nhau tuỳ theo loại xác thực bạn sử dụng:
- Với xác thực ứng dụng, các phương thức chỉ trả về tài nguyên mà Ứng dụng Chat có thể truy cập.
- Với tính năng xác thực người dùng, các phương thức chỉ trả về các tài nguyên mà người dùng có thể truy cập.
Ví dụ: việc gọi phương thức spaces.list() bằng quyền uỷ quyền ứng dụng sẽ trả về danh sách không gian mà ứng dụng Chat là thành viên.
Việc gọi spaces.list() với quyền 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. Ngang bằng
bạn có thể sử dụng cả hai loại
xác thực khi gọi API Chat, tuỳ thuộc vào thiết kế
và các tính năng của ứng dụng Chat.
Đố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 | 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 tính năng Xác thực người dùng:
|
|||
| Liệt kê không gian |
Với tính năng 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 cho 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 tính năng Xác thực người dùng:
|
|||
| Tìm 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 thành viên |
Với tính năng 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á tin nhắn |
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 tính năng Xác thực người dùng:
|
||
| Xoá lượt bày tỏ cảm xúc | — |
Với Xác thực người dùng:
|
||
| Biểu tượng cảm xúc tuỳ chỉnh | ||||
| Tạo biểu tượng cảm xúc tuỳ chỉnh | — |
Với Xác thực người dùng:
|
||
| Xoá biểu tượng cảm xúc tuỳ chỉnh | — |
Với tính năng Xác thực người dùng:
|
||
| Sở hữu biểu tượng cảm xúc tuỳ chỉnh | — |
Với Xác thực người dùng:
|
||
| Liệt kê biểu tượng cảm xúc tuỳ chỉnh | — |
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,
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ê các cách phổ biến mà người dùng tương tác Các ứng dụng nhắn tin 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 | 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ề quy trình 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 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 sử dụng OAuth 2.0, hãy xem Sử dụng OAuth 2.0 để truy cập 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ụ.