Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.
В этом руководстве описывается, как работает шифрование и дешифрование с использованием API шифрования на стороне клиента Google Workspace.
Необходимо добавить в разрешённый список все службы поставщиков удостоверений (IdP), используемые пользователями, обменивающимися зашифрованными файлами. Обычно необходимые данные IdP можно найти в общедоступном файле .wellknown; в противном случае обратитесь к администратору Google Workspace вашей организации, чтобы получить данные IdP.
Шифровать данные
Когда пользователь Google Workspace запрашивает сохранение или хранение данных, зашифрованных на стороне клиента (CSE), Google Workspace отправляет wrap на URL-адрес конечной точки службы управления списками доступа (KACLS) для шифрования. Помимо дополнительных проверок безопасности, таких как проверки периметра и проверки на основе утверждений JWT, ваша служба KACLS должна выполнить следующие действия:
Проверьте, что токены авторизации и аутентификации принадлежат одному и тому же пользователю, выполнив сопоставление заявок электронной почты без учета регистра.
Если токен аутентификации содержит необязательное утверждение google_email , его необходимо сравнить с утверждением email в токене авторизации без учёта регистра. Не используйте утверждение email в токене аутентификации для этого сравнения.
В сценариях, когда в токене аутентификации отсутствует необязательное утверждение google_email , утверждение электронной почты в токене аутентификации следует сравнивать с утверждением электронной почты в токене авторизации, используя метод без учета регистра.
В случаях, когда Google выдаёт токен авторизации для адреса электронной почты, не связанного с учётной записью Google, необходимо наличие утверждения email_type . Это критически важный элемент функции гостевого доступа, предоставляющий KACLS ценную информацию для применения дополнительных мер безопасности к внешним пользователям.
Вот несколько примеров того, как KACLS может использовать эту информацию:
Ввести дополнительные требования по лесозаготовкам.
Требовать дополнительные требования к токене аутентификации.
Если клиент не настроил гостевой доступ, все запросы, в которых email_type установлен на google-visitor или customer-idp могут быть отклонены. Запросы с параметром email_type , установленным на google , или с неустановленным параметром email_type должны по-прежнему приниматься.
Если токен аутентификации содержит необязательное утверждение delegated_to , он также должен содержать утверждение resource_name , и эти два утверждения необходимо сравнить с утверждениями delegated_to и resource_name в токене авторизации. Сравнение утверждений delegated_to следует выполнять без учёта регистра, а resource_name в токенах должно совпадать с resource_name операции.
Проверьте, что в токене авторизации указана rolewriter или upgrader .
Проверьте, соответствует ли утверждение kacls_url в токене авторизации текущему URL-адресу KACLS. Эта проверка позволяет обнаружить потенциальные серверы типа «man-in-the-middle», настроенные инсайдерами или недобросовестными администраторами домена.
Выполните проверку периметра, используя как аутентификационные, так и авторизационные заявки.
Зашифруйте следующие части, используя аутентифицированный алгоритм шифрования:
Ключ шифрования данных (DEK)
Значения resource_name и perimeter_id из токена авторизации
Любые дополнительные конфиденциальные данные
Зарегистрируйте операцию, включая пользователя, ее инициировавшего, resource_name и причину, переданную в запросе.
Возвращает непрозрачный двоичный объект, который Google Workspace сохраняет вместе с зашифрованным объектом и отправляет как есть при любой последующей операции распаковки ключа. Или отправляет структурированный ответ об ошибке .
Двоичный объект должен содержать единственную копию зашифрованного DEK, в нем могут храниться данные, специфичные для реализации.
Расшифровать данные
Когда пользователь Google Workspace запрашивает открытие данных, зашифрованных на стороне клиента (CSE), Google Workspace отправляет запрос unwrap на URL-адрес вашей конечной точки KACLS для расшифровки. Помимо дополнительных проверок безопасности, таких как проверки периметра и проверки на основе утверждений JWT, ваша KACLS должна выполнить следующие действия:
Проверьте, что токены авторизации и аутентификации принадлежат одному и тому же пользователю, выполнив сопоставление заявок электронной почты без учета регистра.
Если токен аутентификации содержит необязательное утверждение google_email , его необходимо сравнить с утверждением email в токене авторизации без учёта регистра. Не используйте утверждение email в токене аутентификации для этого сравнения.
В сценариях, когда в токене аутентификации отсутствует необязательное утверждение google_email , утверждение электронной почты в токене аутентификации следует сравнивать с утверждением электронной почты в токене авторизации, используя метод без учета регистра.
В случаях, когда Google выдаёт токен авторизации для адреса электронной почты, не связанного с учётной записью Google, необходимо наличие утверждения email_type . Это критически важный элемент функции гостевого доступа, предоставляющий KACLS ценную информацию для применения дополнительных мер безопасности к внешним пользователям.
Вот несколько примеров того, как KACLS может использовать эту информацию:
Ввести дополнительные требования по лесозаготовкам.
Требовать дополнительные требования к токене аутентификации.
Если клиент не настроил гостевой доступ, все запросы, в которых email_type установлен на google-visitor или customer-idp могут быть отклонены. Запросы с параметром email_type , установленным на google , или с неустановленным параметром email_type должны по-прежнему приниматься.
Если токен аутентификации содержит необязательное утверждение delegated_to , он также должен содержать утверждение resource_name , и эти два утверждения необходимо сравнить с утверждениями delegated_to и resource_name в токене авторизации. Сравнение утверждений delegated_to следует выполнять без учёта регистра, а resource_name в токенах должно совпадать с resource_name операции.
Проверьте, что в токене авторизации указана rolereader или writer .
Убедитесь, что утверждение kacls_url в токене авторизации соответствует текущему URL-адресу KACLS. Это позволяет обнаружить потенциальные серверы типа «man-in-the-middle», настроенные инсайдерами или недобросовестными администраторами домена.
Расшифруйте следующие части, используя аутентифицированный алгоритм шифрования:
Ключ шифрования данных (DEK)
Значения resource_name и perimeter_id из токена авторизации
Любые дополнительные конфиденциальные данные
Проверьте, совпадают ли resource_name в токене авторизации и расшифрованном блобе.
Выполните проверку периметра, используя как аутентификационные, так и авторизационные заявки.
Зарегистрируйте операцию, включая пользователя, ее инициировавшего, resource_name и причину, переданную в запросе.
[[["Прост для понимания","easyToUnderstand","thumb-up"],["Помог мне решить мою проблему","solvedMyProblem","thumb-up"],["Другое","otherUp","thumb-up"]],[["Отсутствует нужная мне информация","missingTheInformationINeed","thumb-down"],["Слишком сложен/слишком много шагов","tooComplicatedTooManySteps","thumb-down"],["Устарел","outOfDate","thumb-down"],["Проблема с переводом текста","translationIssue","thumb-down"],["Проблемы образцов/кода","samplesCodeIssue","thumb-down"],["Другое","otherDown","thumb-down"]],["Последнее обновление: 2025-08-04 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,["This 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\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 KACLS endpoint URL for encryption. In addition to optional\nsecurity checks, such as perimeter and JWT claim-based checks, your KACLS must\nperform 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 - 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\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 - 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)."]]
