Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Ce guide explique comment le chiffrement et le déchiffrement fonctionnent à l'aide de l'API de chiffrement côté client Google Workspace.
Vous devez ajouter à la liste d'autorisation tous les services de fournisseur d'identité (IdP) utilisés par les utilisateurs qui partagent des fichiers chiffrés. Vous trouverez généralement les informations requises sur l'IdP dans leur fichier .well-known public. Sinon, contactez l'administrateur Google Workspace de l'organisation pour obtenir ces informations.
Chiffrer des données
Lorsqu'un utilisateur Google Workspace demande à enregistrer ou stocker des données chiffrées côté client (CSE), Google Workspace envoie une requête wrap à l'URL de votre point de terminaison du service de liste de contrôle d'accès aux clés (KACLS) pour le chiffrement.
En plus des vérifications de sécurité facultatives, telles que les vérifications basées sur le périmètre et les revendications JWT, votre KACLS doit effectuer les étapes suivantes :
Vérifiez que les jetons d'autorisation et d'authentification sont destinés au même utilisateur en effectuant une correspondance insensible à la casse sur les revendications d'adresse e-mail.
Lorsque le jeton d'authentification contient la revendication google_email facultative, il doit être comparé à la revendication d'adresse e-mail dans le jeton d'autorisation en utilisant une approche insensible à la casse. N'utilisez pas la revendication d'adresse e-mail dans le jeton d'authentification pour cette comparaison.
Dans les scénarios où le jeton d'authentification ne comporte pas la revendication google_email facultative, la revendication d'adresse e-mail dans le jeton d'authentification doit être comparée à la revendication d'adresse e-mail dans le jeton d'autorisation, à l'aide d'une méthode insensible à la casse.
Dans les cas où Google émet un jeton d'autorisation pour une adresse e-mail non associée à un compte Google, la revendication email_type doit être présente.
Cela constitue une partie essentielle de la fonctionnalité d'accès invité, car elle fournit des informations précieuses à KACLS pour appliquer des mesures de sécurité supplémentaires aux utilisateurs externes.
Voici quelques exemples d'utilisation de ces informations par un KACLS :
Pour imposer des exigences de journalisation supplémentaires.
Pour limiter l'émetteur de jetons d'authentification à un IdP invité dédié.
Pour exiger des revendications supplémentaires sur le jeton d'authentification.
Si un client n'a pas configuré l'accès invité, toutes les requêtes où email_type est défini sur google-visitor ou customer-idp peuvent être refusées. Les requêtes avec un email_type de google ou avec un email_type non défini doivent continuer à être acceptées.
Lorsque le jeton d'authentification contient la revendication delegated_to facultative, il doit également contenir la revendication resource_name. Ces deux revendications doivent être comparées aux revendications delegated_to et resource_name du jeton d'autorisation. Les revendications delegated_to doivent être comparées à l'aide d'une approche insensible à la casse, et le resource_name dans les jetons doit correspondre au resource_name de l'opération.
Vérifiez que la revendication role dans le jeton d'autorisation est writer ou upgrader.
Vérifiez que la revendication kacls_url du jeton d'autorisation correspond à l'URL KACLS actuelle. Cette vérification permet de détecter les serveurs d'attaque de l'homme du milieu potentiels configurés par des personnes internes ou des administrateurs de domaine malveillants.
Effectuez une vérification du périmètre à l'aide des revendications d'authentification et d'autorisation.
Chiffrez les parties suivantes à l'aide d'un algorithme de chiffrement authentifié :
Clé de chiffrement des données (DEK)
Les valeurs resource_name et perimeter_id du jeton d'autorisation
Toute autre donnée sensible
Consignez l'opération, y compris l'utilisateur à l'origine de l'opération, le resource_name et le motif transmis dans la requête.
Renvoie un objet binaire opaque à stocker par Google Workspace à côté de l'objet chiffré et à envoyer tel quel lors de toute opération de déchiffrement de clé ultérieure. Vous pouvez également renvoyer une réponse d'erreur structurée.
L'objet binaire doit contenir la seule copie de la DEK chiffrée. Des données spécifiques à l'implémentation peuvent y être stockées.
Déchiffrer des données
Lorsqu'un utilisateur Google Workspace demande à ouvrir des données chiffrées côté client (CSE), Google Workspace envoie une requête unwrap à l'URL de votre point de terminaison KACLS pour le déchiffrement. En plus des contrôles de sécurité facultatifs, tels que les contrôles basés sur le périmètre et les revendications JWT, votre KACLS doit effectuer les étapes suivantes :
Vérifiez que les jetons d'autorisation et d'authentification sont destinés au même utilisateur en effectuant une correspondance insensible à la casse sur les revendications d'adresse e-mail.
Lorsque le jeton d'authentification contient la revendication google_email facultative, il doit être comparé à la revendication d'adresse e-mail dans le jeton d'autorisation en utilisant une approche insensible à la casse. N'utilisez pas la revendication d'adresse e-mail dans le jeton d'authentification pour cette comparaison.
Dans les scénarios où le jeton d'authentification ne comporte pas la revendication google_email facultative, la revendication d'adresse e-mail dans le jeton d'authentification doit être comparée à la revendication d'adresse e-mail dans le jeton d'autorisation, à l'aide d'une méthode insensible à la casse.
Dans les cas où Google émet un jeton d'autorisation pour une adresse e-mail non associée à un compte Google, la revendication email_type doit être présente.
Cela constitue une partie essentielle de la fonctionnalité d'accès invité, car elle fournit des informations précieuses à KACLS pour appliquer des mesures de sécurité supplémentaires aux utilisateurs externes.
Voici quelques exemples d'utilisation de ces informations par un KACLS :
Pour imposer des exigences de journalisation supplémentaires.
Pour limiter l'émetteur de jetons d'authentification à un IdP invité dédié.
Pour exiger des revendications supplémentaires sur le jeton d'authentification.
Si un client n'a pas configuré l'accès invité, toutes les requêtes où email_type est défini sur google-visitor ou customer-idp peuvent être refusées. Les requêtes avec un email_type de google ou avec un email_type non défini doivent continuer à être acceptées.
Lorsque le jeton d'authentification contient la revendication delegated_to facultative, il doit également contenir la revendication resource_name. Ces deux revendications doivent être comparées aux revendications delegated_to et resource_name du jeton d'autorisation. Les revendications delegated_to doivent être comparées à l'aide d'une approche insensible à la casse, et le resource_name dans les jetons doit correspondre au resource_name de l'opération.
Vérifiez que la revendication role dans le jeton d'autorisation est reader ou writer.
Vérifiez que la revendication kacls_url du jeton d'autorisation correspond à l'URL KACLS actuelle. Cela permet de détecter les serveurs potentiels d'attaque de l'homme du milieu configurés par des personnes internes ou des administrateurs de domaine malveillants.
Déchiffrez les parties suivantes à l'aide d'un algorithme de chiffrement authentifié :
Clé de chiffrement des données (DEK)
Les valeurs resource_name et perimeter_id du jeton d'autorisation
Toute autre donnée sensible
Vérifiez que le resource_name du jeton d'autorisation et du blob déchiffré correspondent.
Effectuez une vérification du périmètre à l'aide des revendications d'authentification et d'autorisation.
Consignez l'opération, y compris l'utilisateur à l'origine de l'opération, le resource_name et le motif transmis dans la requête.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/08/29 (UTC).
[null,null,["Dernière mise à jour le 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)."]]
