Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Panduan ini menjelaskan cara kerja enkripsi dan dekripsi menggunakan Google Workspace Client-side Encryption API.
Anda harus memasukkan layanan Penyedia Identitas (IdP) yang digunakan oleh pengguna yang berbagi file terenkripsi ke dalam daftar yang diizinkan. Anda biasanya dapat menemukan detail IdP yang diperlukan di file .well-known yang tersedia secara publik; jika tidak, hubungi administrator Google Workspace organisasi untuk mengetahui detail IdP mereka.
Mengenkripsi data
Saat pengguna Google Workspace meminta untuk menyimpan atau menyimpan data terenkripsi sisi klien (CSE), Google Workspace akan mengirimkan permintaan wrap ke URL endpoint Layanan Daftar Kontrol Akses Kunci (KACLS) Anda untuk enkripsi.
Selain pemeriksaan keamanan opsional, seperti pemeriksaan berbasis klaim JWT dan perimeter, KACLS Anda harus melakukan langkah-langkah berikut:
Periksa apakah token otorisasi dan autentikasi ditujukan untuk pengguna yang sama dengan
mencocokkan klaim email secara tidak peka huruf besar/kecil.
Jika token autentikasi berisi klaim google_email opsional,
klaim tersebut harus dibandingkan dengan klaim email dalam token otorisasi
menggunakan pendekatan yang tidak peka huruf besar/kecil. Jangan gunakan klaim email dalam token autentikasi untuk perbandingan ini.
Dalam skenario saat token autentikasi tidak memiliki klaim
google_email opsional, klaim email dalam token autentikasi
harus dibandingkan dengan klaim email dalam token otorisasi,
menggunakan metode yang tidak peka huruf besar/kecil.
Dalam skenario saat Google mengeluarkan token otorisasi untuk email yang tidak terkait dengan Akun Google, klaim email_type harus ada.
Hal ini merupakan bagian penting dari fitur Akses Tamu, yang memberikan informasi berharga bagi KACLS untuk menerapkan langkah-langkah keamanan tambahan pada pengguna eksternal.
Beberapa contoh cara KACLS dapat menggunakan informasi ini antara lain:
Untuk menerapkan persyaratan logging tambahan.
Untuk membatasi penerbit token autentikasi ke IdP Tamu khusus.
Untuk mewajibkan klaim tambahan pada token autentikasi.
Jika pelanggan belum mengonfigurasi Akses Tamu, semua permintaan dengan email_type disetel ke google-visitor atau customer-idp dapat ditolak. Permintaan dengan email_typegoogle atau dengan email_type yang tidak ditetapkan
harus terus diterima.
Jika token autentikasi berisi klaim delegated_to opsional, token tersebut juga harus berisi klaim resource_name, dan kedua klaim ini harus dibandingkan dengan klaim delegated_to dan resource_name dalam token otorisasi. Klaim delegated_to harus dibandingkan menggunakan pendekatan
yang tidak peka huruf besar/kecil, dan resource_name dalam token harus
cocok dengan resource_name operasi.
Pastikan klaim role dalam token otorisasi adalah writer atau
upgrader.
Pastikan klaim kacls_url di token otorisasi cocok dengan URL KACLS saat ini. Pemeriksaan ini memungkinkan deteksi potensi server man-in-the-middle yang dikonfigurasi oleh orang dalam atau administrator domain jahat.
Lakukan pemeriksaan perimeter menggunakan klaim otorisasi dan autentikasi.
Enkripsi bagian berikut menggunakan algoritma enkripsi yang diautentikasi:
Kunci Enkripsi Data (DEK)
Nilai resource_name dan perimeter_id dari token otorisasi
Data sensitif tambahan
Mencatat operasi, termasuk pengguna yang memulainya, resource_name, dan
alasan yang diteruskan dalam permintaan.
Mengembalikan objek biner buram untuk disimpan oleh Google Workspace bersama dengan objek terenkripsi dan dikirim apa adanya dalam operasi pembukaan kunci berikutnya. Atau, sajikan respons error terstruktur.
Objek biner harus berisi satu-satunya salinan DEK terenkripsi, dan data khusus penerapan dapat disimpan di dalamnya.
Mendekripsi data
Saat pengguna Google Workspace meminta untuk membuka data terenkripsi sisi klien (CSE),
Google Workspace akan mengirim permintaan unwrap
ke URL endpoint KACLS Anda untuk dekripsi. Selain pemeriksaan keamanan opsional, seperti pemeriksaan berbasis klaim JWT dan perimeter, KACLS Anda harus melakukan langkah-langkah berikut:
Periksa apakah token otorisasi dan autentikasi ditujukan untuk pengguna yang sama dengan
mencocokkan klaim email secara tidak peka huruf besar/kecil.
Jika token autentikasi berisi klaim google_email opsional,
klaim tersebut harus dibandingkan dengan klaim email dalam token otorisasi
menggunakan pendekatan yang tidak peka huruf besar/kecil. Jangan gunakan klaim email dalam token autentikasi untuk perbandingan ini.
Dalam skenario saat token autentikasi tidak memiliki klaim
google_email opsional, klaim email dalam token autentikasi
harus dibandingkan dengan klaim email dalam token otorisasi,
menggunakan metode yang tidak peka huruf besar/kecil.
Dalam skenario saat Google mengeluarkan token otorisasi untuk email yang tidak terkait dengan Akun Google, klaim email_type harus ada.
Hal ini merupakan bagian penting dari fitur Akses Tamu, yang memberikan informasi berharga bagi KACLS untuk menerapkan langkah-langkah keamanan tambahan pada pengguna eksternal.
Beberapa contoh cara KACLS dapat menggunakan informasi ini antara lain:
Untuk menerapkan persyaratan logging tambahan.
Untuk membatasi penerbit token autentikasi ke IdP Tamu khusus.
Untuk mewajibkan klaim tambahan pada token autentikasi.
Jika pelanggan belum mengonfigurasi Akses Tamu, semua permintaan dengan email_type disetel ke google-visitor atau customer-idp dapat ditolak. Permintaan dengan email_typegoogle atau dengan email_type yang tidak ditetapkan
harus terus diterima.
Jika token autentikasi berisi klaim delegated_to opsional, token tersebut juga harus berisi klaim resource_name, dan kedua klaim ini harus dibandingkan dengan klaim delegated_to dan resource_name dalam token otorisasi. Klaim delegated_to harus dibandingkan menggunakan pendekatan
yang tidak peka huruf besar/kecil, dan resource_name dalam token harus
cocok dengan resource_name operasi.
Pastikan klaim role dalam token otorisasi adalah reader atau
writer.
Pastikan klaim kacls_url di token otorisasi cocok dengan URL KACLS saat ini. Hal ini memungkinkan deteksi potensi server man-in-the-middle yang dikonfigurasi oleh orang dalam atau administrator domain jahat.
Dekripsi bagian berikut menggunakan algoritma enkripsi yang diautentikasi:
Kunci Enkripsi Data (DEK)
Nilai resource_name dan perimeter_id dari token otorisasi
Data sensitif tambahan
Pastikan resource_name dalam token otorisasi dan blob yang didekripsi cocok.
Lakukan pemeriksaan perimeter menggunakan klaim autentikasi dan otorisasi.
Mencatat operasi, termasuk pengguna yang memulainya, resource_name, dan
alasan yang diteruskan dalam permintaan.
[null,null,["Terakhir diperbarui pada 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)."]]
