Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Hướng dẫn này mô tả cách hoạt động của quy trình mã hoá và giải mã bằng Google Workspace Client-side Encryption API.
Bạn phải đưa mọi dịch vụ Nhà cung cấp dịch vụ danh tính (IdP) mà người dùng sử dụng để chia sẻ tệp được mã hoá vào danh sách cho phép. Thông thường, bạn có thể tìm thấy thông tin cần thiết về nhà cung cấp danh tính trong tệp .well-known có sẵn công khai của họ; nếu không, hãy liên hệ với quản trị viên Google Workspace của tổ chức để biết thông tin về nhà cung cấp danh tính của họ.
Mã hoá dữ liệu
Khi người dùng Google Workspace yêu cầu lưu hoặc lưu trữ dữ liệu được mã hoá phía máy khách (CSE), Google Workspace sẽ gửi yêu cầu wrap đến URL điểm cuối của Dịch vụ danh sách kiểm soát quyền truy cập vào khoá (KACLS) để mã hoá.
Ngoài các bước kiểm tra bảo mật không bắt buộc, chẳng hạn như các bước kiểm tra dựa trên yêu cầu JWT và ranh giới, KACLS của bạn phải thực hiện các bước sau:
Kiểm tra để đảm bảo mã thông báo uỷ quyền và xác thực là của cùng một người dùng bằng cách so khớp không phân biệt chữ hoa chữ thường đối với các yêu cầu về email.
Khi mã xác thực chứa yêu cầu google_email không bắt buộc, bạn phải so sánh mã này với yêu cầu về email trong mã uỷ quyền bằng cách sử dụng phương pháp không phân biệt chữ hoa chữ thường. Không sử dụng yêu cầu về email trong mã thông báo xác thực cho hoạt động so sánh này.
Trong trường hợp mã thông báo xác thực thiếu yêu cầu google_email không bắt buộc, bạn nên so sánh yêu cầu email trong mã thông báo xác thực với yêu cầu email trong mã thông báo uỷ quyền bằng phương thức không phân biệt chữ hoa chữ thường.
Trong trường hợp Google cấp mã thông báo uỷ quyền cho một email không được liên kết với Tài khoản Google, thì phải có xác nhận quyền sở hữu email_type.
Đây là một phần quan trọng của tính năng Quyền truy cập của khách, cung cấp thông tin có giá trị cho KACLS để thực thi các biện pháp bảo mật bổ sung đối với người dùng bên ngoài.
Sau đây là một số ví dụ về cách KACLS có thể sử dụng thông tin này:
Để áp đặt các yêu cầu bổ sung về việc ghi nhật ký.
Để hạn chế nhà phát hành mã thông báo xác thực đối với một IdP khách chuyên dụng.
Để yêu cầu các xác nhận quyền sở hữu bổ sung trên mã thông báo xác thực.
Nếu khách hàng chưa định cấu hình Quyền truy cập của khách, thì tất cả các yêu cầu mà email_type được đặt thành google-visitor hoặc customer-idp đều có thể bị từ chối. Các yêu cầu có email_type là google hoặc có email_type chưa đặt sẽ tiếp tục được chấp nhận.
Khi mã xác thực chứa khai báo delegated_to không bắt buộc, mã này cũng phải chứa khai báo resource_name và hai khai báo này phải được so sánh với khai báo delegated_to và resource_name trong mã uỷ quyền. Bạn nên so sánh các delegated_to theo cách không phân biệt chữ hoa chữ thường và resource_name trong mã thông báo phải khớp với resource_name của thao tác.
Kiểm tra để đảm bảo rằng thông báo xác nhận quyền sở hữu role trong mã thông báo uỷ quyền là writer hoặc upgrader.
Kiểm tra để đảm bảo rằng yêu cầu kacls_url trong mã thông báo uỷ quyền khớp với URL KACLS hiện tại. Quy trình kiểm tra này cho phép phát hiện các máy chủ trung gian tiềm ẩn do người nội bộ hoặc quản trị viên miền giả mạo định cấu hình.
Thực hiện kiểm tra ranh giới bằng cả xác thực và uỷ quyền.
Mã hoá các phần sau bằng một thuật toán mã hoá đã xác thực:
Khoá mã hoá dữ liệu (DEK)
Giá trị resource_name và perimeter_id trong mã thông báo uỷ quyền
Mọi dữ liệu nhạy cảm bổ sung
Ghi lại thao tác, bao gồm cả người dùng bắt nguồn thao tác đó, resource_name và lý do được truyền trong yêu cầu.
Trả về một đối tượng nhị phân không trong suốt để Google Workspace lưu trữ cùng với đối tượng được mã hoá và gửi nguyên trạng trong mọi thao tác mở khoá tiếp theo. Hoặc phân phát một phản hồi lỗi có cấu trúc.
Đối tượng nhị phân phải chứa bản sao duy nhất của DEK đã mã hoá, dữ liệu cụ thể về việc triển khai có thể được lưu trữ trong đó.
Giải mã dữ liệu
Khi người dùng Google Workspace yêu cầu mở dữ liệu được mã hoá phía máy khách (CSE), Google Workspace sẽ gửi yêu cầu unwrap đến URL điểm cuối KACLS của bạn để giải mã. Ngoài các bước kiểm tra bảo mật không bắt buộc, chẳng hạn như các bước kiểm tra dựa trên phạm vi và JWT, KACLS của bạn phải thực hiện các bước sau:
Kiểm tra để đảm bảo mã thông báo uỷ quyền và xác thực là của cùng một người dùng bằng cách so khớp không phân biệt chữ hoa chữ thường đối với các yêu cầu về email.
Khi mã xác thực chứa yêu cầu google_email không bắt buộc, bạn phải so sánh mã này với yêu cầu về email trong mã uỷ quyền bằng cách sử dụng phương pháp không phân biệt chữ hoa chữ thường. Không sử dụng yêu cầu về email trong mã thông báo xác thực cho hoạt động so sánh này.
Trong trường hợp mã thông báo xác thực thiếu yêu cầu google_email không bắt buộc, bạn nên so sánh yêu cầu email trong mã thông báo xác thực với yêu cầu email trong mã thông báo uỷ quyền bằng phương thức không phân biệt chữ hoa chữ thường.
Trong trường hợp Google cấp mã thông báo uỷ quyền cho một email không được liên kết với Tài khoản Google, thì phải có xác nhận quyền sở hữu email_type.
Đây là một phần quan trọng của tính năng Quyền truy cập của khách, cung cấp thông tin có giá trị cho KACLS để thực thi các biện pháp bảo mật bổ sung đối với người dùng bên ngoài.
Sau đây là một số ví dụ về cách KACLS có thể sử dụng thông tin này:
Để áp đặt các yêu cầu bổ sung về việc ghi nhật ký.
Để hạn chế nhà phát hành mã thông báo xác thực đối với một IdP khách chuyên dụng.
Để yêu cầu các xác nhận quyền sở hữu bổ sung trên mã thông báo xác thực.
Nếu khách hàng chưa định cấu hình Quyền truy cập của khách, thì tất cả các yêu cầu mà email_type được đặt thành google-visitor hoặc customer-idp đều có thể bị từ chối. Các yêu cầu có email_type là google hoặc có email_type chưa đặt sẽ tiếp tục được chấp nhận.
Khi mã xác thực chứa khai báo delegated_to không bắt buộc, mã này cũng phải chứa khai báo resource_name và hai khai báo này phải được so sánh với khai báo delegated_to và resource_name trong mã uỷ quyền. Bạn nên so sánh các delegated_to theo cách không phân biệt chữ hoa chữ thường và resource_name trong mã thông báo phải khớp với resource_name của thao tác.
Kiểm tra để đảm bảo rằng thông báo xác nhận quyền sở hữu role trong mã thông báo uỷ quyền là reader hoặc writer.
Kiểm tra để đảm bảo rằng yêu cầu kacls_url trong mã thông báo uỷ quyền khớp với URL KACLS hiện tại. Điều này cho phép phát hiện các máy chủ trung gian tiềm ẩn do người nội bộ hoặc quản trị viên miền giả mạo định cấu hình.
Giải mã các phần sau bằng một thuật toán mã hoá đã xác thực:
Khoá mã hoá dữ liệu (DEK)
Giá trị resource_name và perimeter_id trong mã thông báo uỷ quyền
Mọi dữ liệu nhạy cảm bổ sung
Kiểm tra để đảm bảo resource_name trong mã thông báo uỷ quyền và blob đã giải mã khớp nhau.
Thực hiện kiểm tra ranh giới bằng cả xác thực và uỷ quyền.
Ghi lại thao tác, bao gồm cả người dùng bắt nguồn thao tác đó, resource_name và lý do được truyền trong yêu cầu.
[null,null,["Cập nhật lần gần đây nhất: 2025-08-29 UTC."],[[["\u003cp\u003eThis guide outlines the process of encrypting and decrypting data using the Google Workspace Client-side Encryption API, leveraging a Key Access and Control List Service (KACLS).\u003c/p\u003e\n"],["\u003cp\u003eDuring encryption, the KACLS validates the user, encrypts the data encryption key (DEK) and other sensitive data, logs the operation, and returns an opaque binary object containing the encrypted DEK to Google Workspace for storage.\u003c/p\u003e\n"],["\u003cp\u003eFor decryption, the KACLS validates the user, decrypts the DEK and associated data, verifies the resource name, performs a perimeter check, logs the operation, and returns the unwrapped DEK to Google Workspace.\u003c/p\u003e\n"],["\u003cp\u003eBefore sharing encrypted files, ensure to allowlist any Identity Provider (IdP) services used by the intended recipients, which typically involves obtaining IdP details from their publicly available .well-known file or contacting their Google Workspace administrator.\u003c/p\u003e\n"]]],["When users encrypt data, the KACLS must validate user authentication and authorization tokens, ensuring matching email claims and specific role and URL claims. It encrypts the Data Encryption Key (DEK), `resource_name`, `perimeter_id`, and other sensitive data, logs the operation, and returns an encrypted object. For decryption, the process mirrors encryption, validating tokens, decrypting the data, verifying `resource_name`, performing perimeter checks, logging, and returning the DEK. Guest access requires extra checks. Identity provider services must be allowlisted.\n"],null,["# Encrypt & decrypt data\n\nThis guide describes how encryption and decryption works using the Google Workspace Client-side Encryption API.\n\nYou must allowlist any Identity Provider (IdP) services used by users\nsharing encrypted files. You can usually find the required IdP details in their\npublicly-available .well-known file; otherwise, contact the organization's\nGoogle Workspace administrator for their IdP details.\n\nEncrypt data\n------------\n\nWhen a Google Workspace user requests to save or store client-side encrypted\n(CSE) data, Google Workspace sends a [`wrap`](/workspace/cse/reference/wrap)\nrequest to your Key Access Control List Service (KACLS) endpoint URL for encryption.\nIn addition to optional security checks, such as perimeter and JWT claim-based checks,\nyour KACLS must perform the following steps:\n\n1. Validate the requesting user.\n\n - Validate both the [authentication token](/workspace/cse/reference/authentication-tokens) and [authorization token](/workspace/cse/reference/authorization-tokens).\n - Check that authorization and authentication tokens are for the same user by doing a case-insensitive match on the email claims.\n - When the authentication token contains the optional `google_email` claim, it must be compared against the email claim in the authorization token using a case-insensitive approach. Don't use the email claim within the authentication token for this comparison.\n - In scenarios where the authentication token lacks the optional `google_email` claim, the email claim within the authentication token should be compared with the email claim in the authorization token, using a case-insensitive method.\n - In scenarios where Google issues an authorization token for an email not associated with a Google Account, the `email_type` claim must be present. This forms a crucial part of the Guest Access feature, providing valuable information for KACLS to enforce additional security measures on external users.\n - Some examples of how a KACLS can use this information include:\n - To impose additional logging requirements.\n - To restrict the authentication token issuer to a dedicated Guest IdP.\n - To require additional claims on the authentication token.\n - If a customer has not configured Guest Access, then all requests where `email_type` is set to `google-visitor` or `customer-idp` can be rejected. Requests with an `email_type` of `google` or with an unset `email_type` should continue to be accepted.\n - When the authentication token contains the optional `delegated_to` claim, it must also contain the `resource_name` claim, and these two claims must be compared against the `delegated_to` and `resource_name` claims in the authorization token. The `delegated_to` claims should be compared using a case-insensitive approach, and the `resource_name` in the tokens should match the `resource_name` of the operation.\n - Check that the `role` claim in the authorization token is `writer` or `upgrader`.\n - Check that the `kacls_url` claim in the authorization token matches the current KACLS URL. This check allows detection of potential man-in-the-middle servers configured by insiders or rogue domain administrators.\n - Perform a perimeter check using both authentication and authorization claims.\n2. Encrypt the following parts using an authenticated encryption algorithm:\n\n - Data Encryption Key (DEK)\n - The `resource_name` and `perimeter_id` values from the authorization token\n - Any additional sensitive data\n3. Log the operation, including the user originating it, the `resource_name` and\n the reason passed in the request.\n\n4. Return an opaque binary object to be stored by Google Workspace alongside\n the encrypted object and sent as-is in any subsequent key unwrapping\n operation. Or, serve a [structured error reply](/workspace/cse/reference/structured-errors).\n\n - The binary object should contain the only copy of the encrypted DEK, implementation specific data can be stored in it.\n\n| **Note:** Do not store the DEK in your KACLS system. Instead, encrypt it and return it in the `wrapped_key` object to prevent discrepancies for the lifetime of the file. Google doesn't send deletion requests to the KACLS when objects are deleted.\n\nDecrypt data\n------------\n\nWhen a Google Workspace user requests to open client-side encrypted (CSE) data,\nGoogle Workspace sends an [`unwrap`](/workspace/cse/reference/unwrap) request\nto your KACLS endpoint URL for decryption. In addition to optional security\nchecks, such as perimeter and JWT claim-based checks, your KACLS must perform\nthe following steps:\n\n1. Validate the requesting user.\n\n - Validate both the [authentication token](/workspace/cse/reference/authentication-tokens) and [authorization token](/workspace/cse/reference/authorization-tokens).\n - Check that authorization and authentication tokens are for the same user by doing a case-insensitive match on the email claims.\n - When the authentication token contains the optional `google_email` claim, it must be compared against the email claim in the authorization token using a case-insensitive approach. Don't use the email claim within the authentication token for this comparison.\n - In scenarios where the authentication token lacks the optional `google_email` claim, the email claim within the authentication token should be compared with the email claim in the authorization token, using a case-insensitive method.\n - In scenarios where Google issues an authorization token for an email not associated with a Google Account, the `email_type` claim must be present. This forms a crucial part of the Guest Access feature, providing valuable information for KACLS to enforce additional security measures on external users.\n - Some examples of how a KACLS can use this information include:\n - To impose additional logging requirements.\n - To restrict the authentication token issuer to a dedicated Guest IdP.\n - To require additional claims on the authentication token.\n - If a customer has not configured Guest Access, then all requests where `email_type` is set to `google-visitor` or `customer-idp` can be rejected. Requests with an `email_type` of `google` or with an unset `email_type` should continue to be accepted.\n - When the authentication token contains the optional `delegated_to` claim, it must also contain the `resource_name` claim, and these two claims must be compared against the `delegated_to` and `resource_name` claims in the authorization token. The `delegated_to` claims should be compared using a case-insensitive approach, and the `resource_name` in the tokens should match the `resource_name` of the operation.\n - Check that the `role` claim in the authorization token is `reader` or `writer`.\n - Check that the `kacls_url` claim in the authorization token matches the current KACLS URL. This allows detection of potential man-in-the-middle servers configured by insiders or rogue domain administrators.\n2. Decrypt the following parts using an authenticated encryption algorithm:\n\n - Data Encryption Key (DEK)\n - The `resource_name` and `perimeter_id` values from the authorization token\n - Any additional sensitive data\n3. Check that the `resource_name` in the authorization token and decrypted blob\n match.\n\n4. Perform a perimeter check using both authentication and authorization claims.\n\n5. Log the operation, including the user originating it, the `resource_name` and\n the reason passed in the request.\n\n6. Return the unwrapped DEK or a [structured error reply](/workspace/cse/reference/structured-errors).\n\n| **Note:** To decrypt [Google Takeout](https://support.google.com/a/answer/100458) requests, see [`takeout_unwrap`](/workspace/cse/reference/takeout_unwrap)."]]
