Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
In diesem Leitfaden wird beschrieben, wie die Verschlüsselung und Entschlüsselung mit der Google Workspace Client-side Encryption API funktioniert.
Sie müssen alle Identitätsanbieterdienste (Identity Provider, IdP) auf die Zulassungsliste setzen, die von Nutzern verwendet werden, die verschlüsselte Dateien freigeben. Normalerweise finden Sie die erforderlichen IdP-Details in der öffentlichen .well-known-Datei. Andernfalls können Sie den Google Workspace-Administrator der Organisation um die Informationen zum IdP bitten.
Daten verschlüsseln
Wenn ein Google Workspace-Nutzer clientseitig verschlüsselte (CSE) Daten speichern oder aufbewahren möchte, sendet Google Workspace eine wrap-Anfrage zur Verschlüsselung an die Endpunkt-URL Ihres Key Access Control List Service (KACLS).
Zusätzlich zu optionalen Sicherheitsprüfungen wie Perimeter- und JWT-Anspruchsprüfungen müssen Ihre KACLS die folgenden Schritte ausführen:
Prüfen Sie, ob Autorisierungs- und Authentifizierungstokens für denselben Nutzer gelten, indem Sie die E-Mail-Ansprüche ohne Berücksichtigung der Groß-/Kleinschreibung vergleichen.
Wenn das Authentifizierungstoken den optionalen Anspruch google_email enthält, muss es mit dem Anspruch „email“ im Autorisierungstoken verglichen werden. Dabei muss die Groß-/Kleinschreibung ignoriert werden. Verwenden Sie für diesen Vergleich nicht den E-Mail-Claim im Authentifizierungstoken.
In Szenarien, in denen das Authentifizierungstoken den optionalen google_email-Anspruch nicht enthält, sollte der E-Mail-Anspruch im Authentifizierungstoken mit dem E-Mail-Anspruch im Autorisierungstoken verglichen werden. Dabei sollte eine Methode verwendet werden, bei der die Groß- und Kleinschreibung keine Rolle spielt.
Wenn Google ein Autorisierungstoken für eine E-Mail-Adresse ausstellt, die nicht mit einem Google-Konto verknüpft ist, muss der email_type-Anspruch vorhanden sein.
Dies ist ein wichtiger Bestandteil der Gastzugriffsfunktion und liefert wertvolle Informationen für KACLS, um zusätzliche Sicherheitsmaßnahmen für externe Nutzer zu erzwingen.
Hier einige Beispiele dafür, wie ein KACLS diese Informationen verwenden kann:
Zusätzliche Anforderungen an das Logging durchzusetzen.
So beschränken Sie den Aussteller von Authentifizierungstokens auf einen bestimmten Gast-IdP.
Zusätzliche Ansprüche für das Authentifizierungstoken erforderlich machen
Wenn ein Kunde keinen Gastzugriff konfiguriert hat, können alle Anfragen, bei denen email_type auf google-visitor oder customer-idp gesetzt ist, abgelehnt werden. Anfragen mit einem email_type von google oder mit einem nicht festgelegten email_type sollten weiterhin akzeptiert werden.
Wenn das Authentifizierungstoken die optionale Anforderung delegated_to enthält, muss es auch die Anforderung resource_name enthalten. Diese beiden Anforderungen müssen mit den Anforderungen delegated_to und resource_name im Autorisierungstoken verglichen werden. Die delegated_to-Ansprüche sollten mit einem nicht berücksichtigenden Ansatz verglichen werden und die resource_name in den Tokens sollte mit der resource_name des Vorgangs übereinstimmen.
Prüfen Sie, ob der Anspruch role im Autorisierungstoken writer oder upgrader ist.
Prüfen Sie, ob die Anforderung kacls_url im Autorisierungstoken mit der aktuellen KACLS-URL übereinstimmt. Mit dieser Prüfung können potenzielle Man-in-the-Middle-Server erkannt werden, die von Insidern oder betrügerischen Domainadministratoren konfiguriert wurden.
Führen Sie eine Perimeterprüfung mit Authentifizierungs- und Autorisierungsansprüchen durch.
Verschlüsseln Sie die folgenden Teile mit einem Algorithmus für authentifizierte Verschlüsselung:
Die Werte resource_name und perimeter_id aus dem Autorisierungstoken
Alle zusätzlichen sensiblen Daten
Protokollieren Sie den Vorgang, einschließlich des Nutzers, der ihn initiiert hat, der resource_name und des in der Anfrage übergebenen Grunds.
Gibt ein undurchsichtiges binäres Objekt zurück, das von Google Workspace zusammen mit dem verschlüsselten Objekt gespeichert und bei jedem nachfolgenden Entschlüsselungsvorgang unverändert gesendet wird. Oder Sie senden eine strukturierte Fehlerantwort.
Das binäre Objekt sollte die einzige Kopie des verschlüsselten DEK enthalten. Implementierungsspezifische Daten können darin gespeichert werden.
Daten entschlüsseln
Wenn ein Google Workspace-Nutzer anfordert, clientseitig verschlüsselte Daten zu öffnen, sendet Google Workspace eine unwrap-Anfrage zur Entschlüsselung an die KACLS-Endpunkt-URL. Zusätzlich zu optionalen Sicherheitsprüfungen wie Perimeter- und JWT-Anforderungsprüfungen muss Ihr KACLS die folgenden Schritte ausführen:
Prüfen Sie, ob Autorisierungs- und Authentifizierungstokens für denselben Nutzer gelten, indem Sie die E-Mail-Ansprüche ohne Berücksichtigung der Groß-/Kleinschreibung vergleichen.
Wenn das Authentifizierungstoken den optionalen Anspruch google_email enthält, muss es mit dem Anspruch „email“ im Autorisierungstoken verglichen werden. Dabei muss die Groß-/Kleinschreibung ignoriert werden. Verwenden Sie für diesen Vergleich nicht den E-Mail-Claim im Authentifizierungstoken.
In Szenarien, in denen das Authentifizierungstoken den optionalen google_email-Anspruch nicht enthält, sollte der E-Mail-Anspruch im Authentifizierungstoken mit dem E-Mail-Anspruch im Autorisierungstoken verglichen werden. Dabei sollte eine Methode verwendet werden, bei der die Groß- und Kleinschreibung keine Rolle spielt.
Wenn Google ein Autorisierungstoken für eine E-Mail-Adresse ausstellt, die nicht mit einem Google-Konto verknüpft ist, muss der email_type-Anspruch vorhanden sein.
Dies ist ein wichtiger Bestandteil der Gastzugriffsfunktion und liefert wertvolle Informationen für KACLS, um zusätzliche Sicherheitsmaßnahmen für externe Nutzer zu erzwingen.
Hier einige Beispiele dafür, wie ein KACLS diese Informationen verwenden kann:
Zusätzliche Anforderungen an das Logging durchzusetzen.
So beschränken Sie den Aussteller von Authentifizierungstokens auf einen bestimmten Gast-IdP.
Zusätzliche Ansprüche für das Authentifizierungstoken erforderlich machen
Wenn ein Kunde keinen Gastzugriff konfiguriert hat, können alle Anfragen, bei denen email_type auf google-visitor oder customer-idp gesetzt ist, abgelehnt werden. Anfragen mit einem email_type von google oder mit einem nicht festgelegten email_type sollten weiterhin akzeptiert werden.
Wenn das Authentifizierungstoken die optionale Anforderung delegated_to enthält, muss es auch die Anforderung resource_name enthalten. Diese beiden Anforderungen müssen mit den Anforderungen delegated_to und resource_name im Autorisierungstoken verglichen werden. Die delegated_to-Ansprüche sollten mit einem nicht berücksichtigenden Ansatz verglichen werden und die resource_name in den Tokens sollte mit der resource_name des Vorgangs übereinstimmen.
Prüfen Sie, ob der Anspruch role im Autorisierungstoken reader oder writer ist.
Prüfen Sie, ob die Anforderung kacls_url im Autorisierungstoken mit der aktuellen KACLS-URL übereinstimmt. So können potenzielle Man-in-the-Middle-Server erkannt werden, die von Insidern oder betrügerischen Domainadministratoren konfiguriert wurden.
Entschlüsseln Sie die folgenden Teile mit einem Algorithmus für authentifizierte Verschlüsselung:
[null,null,["Zuletzt aktualisiert: 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)."]]
