Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Ten przewodnik opisuje, jak działa szyfrowanie i odszyfrowywanie za pomocą interfejsu Google Workspace Client-side Encryption API.
Musisz dodać do listy dozwolonych wszystkie usługi dostawcy tożsamości używane przez użytkowników udostępniających zaszyfrowane pliki. Wymagane szczegółowe informacje o dostawcy tożsamości można zwykle znaleźć w publicznie dostępnym pliku .well-known. W przeciwnym razie skontaktuj się z administratorem Google Workspace w organizacji, aby uzyskać szczegółowe informacje o dostawcy tożsamości.
Szyfrowanie danych
Gdy użytkownik Google Workspace poprosi o zapisanie lub przechowywanie danych zaszyfrowanych po stronie klienta, Google Workspace wyśle żądanie wrap do adresu URL punktu końcowego usługi listy kontroli dostępu do kluczy (KACLS) w celu zaszyfrowania danych. Oprócz opcjonalnych kontroli bezpieczeństwa, takich jak kontrole oparte na obwodzie i na roszczeniach JWT, KACLS musi wykonać te czynności:
Sprawdź, czy użytkownik wysyłający prośbę jest uprawniony.
Sprawdź, czy tokeny autoryzacji i uwierzytelniania należą do tego samego użytkownika, przeprowadzając dopasowanie bez uwzględniania wielkości liter w przypadku roszczeń dotyczących adresu e-mail.
Jeśli token uwierzytelniania zawiera opcjonalne roszczenie google_email, musi ono zostać porównane z roszczeniem dotyczącym adresu e-mail w tokenie autoryzacji z uwzględnieniem wielkości liter. Nie używaj roszczenia dotyczącego adresu e-mail w tokenie uwierzytelniającym na potrzeby tego porównania.
W sytuacjach, w których token uwierzytelniania nie zawiera opcjonalnego roszczenia google_email, roszczenie dotyczące adresu e-mail w tokenie uwierzytelniania należy porównać z roszczeniem dotyczącym adresu e-mail w tokenie autoryzacyjnym, używając metody bez uwzględniania wielkości liter.
W sytuacjach, w których Google wydaje token autoryzacji dla adresu e-mail, który nie jest powiązany z kontem Google, musi być obecne roszczenie email_type. Jest to kluczowy element funkcji dostępu gościa, który dostarcza listom kontroli dostępu do kluczy (KACL) cennych informacji umożliwiających egzekwowanie dodatkowych środków bezpieczeństwa w przypadku użytkowników zewnętrznych.
Oto kilka przykładów wykorzystania tych informacji przez KACLS:
nałożyć dodatkowe wymagania dotyczące logowania;
Aby ograniczyć wystawcę tokena uwierzytelniającego do dedykowanego dostawcy tożsamości dla gości.
Wymaganie dodatkowych roszczeń w tokenie uwierzytelniania.
Jeśli klient nie skonfigurował dostępu dla gości, wszystkie żądania, w których parametr email_type ma wartość google-visitor lub customer-idp, mogą zostać odrzucone. Prośby z wartością email_type równą google lub z nieustawionym parametrem email_type powinny być nadal akceptowane.
Jeśli token uwierzytelniania zawiera opcjonalne roszczenie delegated_to, musi też zawierać roszczenie resource_name. Te 2 roszczenia muszą być porównywane z roszczeniami delegated_to i resource_name w tokenie autoryzacji. Roszczenia delegated_to należy porównywać bez uwzględniania wielkości liter, a wartość resource_name w tokenach powinna być zgodna z wartością resource_name operacji.
Sprawdź, czy roszczenie role w tokenie autoryzacji ma wartość writer lub upgrader.
Sprawdź, czy roszczenie kacls_url w tokenie autoryzacji jest zgodne z bieżącym adresem URL usługi KACLS. Ta kontrola umożliwia wykrywanie potencjalnych serwerów typu „man-in-the-middle” skonfigurowanych przez osoby z wewnątrz organizacji lub nieuczciwych administratorów domen.
Przeprowadź kontrolę obwodową za pomocą roszczeń uwierzytelniania i autoryzacji.
Zaszyfruj te części za pomocą algorytmu szyfrowania z uwierzytelnianiem:
Klucz szyfrujący dane (DEK)
Wartości resource_name i perimeter_id z tokena autoryzacji
wszelkie dodatkowe dane wrażliwe,
Zarejestruj operację, w tym użytkownika, który ją zainicjował, resource_name i przyczynę przekazaną w żądaniu.
Zwraca nieprzezroczysty obiekt binarny, który ma być przechowywany przez Google Workspace obok zaszyfrowanego obiektu i wysyłany w stanie nienaruszonym w ramach kolejnych operacji odszyfrowywania klucza. Możesz też wyświetlić odpowiedź o określonej strukturze.
Obiekt binarny powinien zawierać tylko kopię zaszyfrowanego klucza DEK. Można w nim przechowywać dane specyficzne dla implementacji.
Odszyfrowywanie danych
Gdy użytkownik Google Workspace poprosi o otwarcie danych zaszyfrowanych po stronie klienta, Google Workspace wyśle unwrap żądanie do adresu URL punktu końcowego KACLS w celu odszyfrowania. Oprócz opcjonalnych kontroli bezpieczeństwa, takich jak kontrole obwodowe i kontrole oparte na roszczeniach JWT, usługa KACLS musi wykonać te czynności:
Sprawdź, czy użytkownik wysyłający prośbę jest uprawniony.
Sprawdź, czy tokeny autoryzacji i uwierzytelniania należą do tego samego użytkownika, przeprowadzając dopasowanie bez uwzględniania wielkości liter w przypadku roszczeń dotyczących adresu e-mail.
Jeśli token uwierzytelniania zawiera opcjonalne roszczenie google_email, musi ono zostać porównane z roszczeniem dotyczącym adresu e-mail w tokenie autoryzacji z uwzględnieniem wielkości liter. Nie używaj roszczenia dotyczącego adresu e-mail w tokenie uwierzytelniającym na potrzeby tego porównania.
W sytuacjach, w których token uwierzytelniania nie zawiera opcjonalnego roszczenia google_email, roszczenie dotyczące adresu e-mail w tokenie uwierzytelniania należy porównać z roszczeniem dotyczącym adresu e-mail w tokenie autoryzacyjnym, używając metody bez uwzględniania wielkości liter.
W sytuacjach, w których Google wydaje token autoryzacji dla adresu e-mail, który nie jest powiązany z kontem Google, musi być obecne roszczenie email_type. Jest to kluczowy element funkcji dostępu gościa, który dostarcza listom kontroli dostępu do kluczy (KACL) cennych informacji umożliwiających egzekwowanie dodatkowych środków bezpieczeństwa w przypadku użytkowników zewnętrznych.
Oto kilka przykładów wykorzystania tych informacji przez KACLS:
nałożyć dodatkowe wymagania dotyczące logowania;
Aby ograniczyć wystawcę tokena uwierzytelniającego do dedykowanego dostawcy tożsamości dla gości.
Wymaganie dodatkowych roszczeń w tokenie uwierzytelniania.
Jeśli klient nie skonfigurował dostępu dla gości, wszystkie żądania, w których parametr email_type ma wartość google-visitor lub customer-idp, mogą zostać odrzucone. Prośby z wartością email_type równą google lub z nieustawionym parametrem email_type powinny być nadal akceptowane.
Jeśli token uwierzytelniania zawiera opcjonalne roszczenie delegated_to, musi też zawierać roszczenie resource_name. Te 2 roszczenia muszą być porównywane z roszczeniami delegated_to i resource_name w tokenie autoryzacji. Roszczenia delegated_to należy porównywać bez uwzględniania wielkości liter, a wartość resource_name w tokenach powinna być zgodna z wartością resource_name operacji.
Sprawdź, czy roszczenie role w tokenie autoryzacji ma wartość reader lub writer.
Sprawdź, czy roszczenie kacls_url w tokenie autoryzacji jest zgodne z bieżącym adresem URL usługi KACLS. Umożliwia to wykrywanie potencjalnych serwerów typu „man-in-the-middle” skonfigurowanych przez osoby z wewnątrz organizacji lub nieuczciwych administratorów domen.
Odszyfruj te części za pomocą algorytmu szyfrowania z uwierzytelnianiem:
Klucz szyfrujący dane (DEK)
Wartości resource_name i perimeter_id z tokena autoryzacji
wszelkie dodatkowe dane wrażliwe,
Sprawdź, czy znak resource_name w tokenie autoryzacji i odszyfrowanym obiekcie blob jest taki sam.
Przeprowadź kontrolę obwodową za pomocą roszczeń dotyczących uwierzytelniania i autoryzacji.
Zarejestruj operację, w tym użytkownika, który ją zainicjował, resource_name i przyczynę przekazaną w żądaniu.
[[["Łatwo zrozumieć","easyToUnderstand","thumb-up"],["Rozwiązało to mój problem","solvedMyProblem","thumb-up"],["Inne","otherUp","thumb-up"]],[["Brak potrzebnych mi informacji","missingTheInformationINeed","thumb-down"],["Zbyt skomplikowane / zbyt wiele czynności do wykonania","tooComplicatedTooManySteps","thumb-down"],["Nieaktualne treści","outOfDate","thumb-down"],["Problem z tłumaczeniem","translationIssue","thumb-down"],["Problem z przykładami/kodem","samplesCodeIssue","thumb-down"],["Inne","otherDown","thumb-down"]],["Ostatnia aktualizacja: 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)."]]
