이 가이드에서는 Google Workspace 클라이언트 측 암호화 API를 사용하여 암호화 및 복호화가 작동하는 방식을 설명합니다.
암호화된 파일을 공유하는 사용자가 사용하는 ID 공급업체 (IdP) 서비스를 허용 목록에 추가해야 합니다. 일반적으로 공개적으로 사용 가능한 .well-known 파일에서 필요한 IdP 세부정보를 찾을 수 있습니다. 그렇지 않은 경우 조직의 Google Workspace 관리자에게 IdP 세부정보를 문의하세요.
데이터 암호화
Google Workspace 사용자가 클라이언트 측 암호화(CSE) 데이터를 저장하거나 보관하도록 요청하면 Google Workspace에서 암호화를 위해 키 액세스 제어 목록 서비스 (KACLS) 엔드포인트 URL에 wrap 요청을 전송합니다.
선택적 보안 검사(예: 경계 및 JWT 클레임 기반 검사) 외에도 KACLS는 다음 단계를 실행해야 합니다.
이메일 클레임에 대해 대소문자를 구분하지 않는 일치를 실행하여 승인 및 인증 토큰이 동일한 사용자를 위한 것인지 확인합니다.
인증 토큰에 선택적 google_email 클레임이 포함된 경우 대소문자를 구분하지 않는 접근 방식을 사용하여 승인 토큰의 이메일 클레임과 비교해야 합니다. 이 비교를 위해 인증 토큰 내에서 이메일 클레임을 사용하지 마세요.
인증 토큰에 선택적 google_email 클레임이 없는 시나리오에서는 인증 토큰 내의 이메일 클레임을 대소문자를 구분하지 않는 방법을 사용하여 승인 토큰의 이메일 클레임과 비교해야 합니다.
Google 계정과 연결되지 않은 이메일에 대해 Google에서 승인 토큰을 발급하는 시나리오에서는 email_type 클레임이 있어야 합니다.
이는 게스트 액세스 기능의 중요한 부분으로, KACLS가 외부 사용자에게 추가 보안 조치를 적용할 수 있는 유용한 정보를 제공합니다.
KACLS가 이 정보를 사용하는 방법의 예는 다음과 같습니다.
추가 로깅 요구사항을 적용합니다.
인증 토큰 발급자를 전용 게스트 IdP로 제한합니다.
인증 토큰에 추가 클레임을 요구합니다.
고객이 게스트 액세스를 구성하지 않은 경우 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과 일치해야 합니다.
승인 토큰의 role 클레임이 writer 또는 upgrader인지 확인합니다.
승인 토큰의 kacls_url 클레임이 현재 KACLS URL과 일치하는지 확인합니다. 이 검사를 통해 내부자 또는 악성 도메인 관리자가 구성한 잠재적인 중간자 서버를 감지할 수 있습니다.
인증 및 승인 클레임을 모두 사용하여 경계 검사를 실행합니다.
인증된 암호화 알고리즘을 사용하여 다음 부분을 암호화합니다.
데이터 암호화 키 (DEK)
승인 토큰의 resource_name 및 perimeter_id 값
추가 민감한 정보
작업을 기록합니다. 여기에는 작업을 시작한 사용자, resource_name, 요청에 전달된 이유가 포함됩니다.
암호화된 객체와 함께 Google Workspace에 저장되고 후속 키 래핑 해제 작업에서 그대로 전송될 불투명 바이너리 객체를 반환합니다. 또는 구조화된 오류 응답을 제공합니다.
바이너리 객체에는 암호화된 DEK의 사본 하나만 포함되어야 하며 구현 관련 데이터는 여기에 저장할 수 있습니다.
데이터 복호화
Google Workspace 사용자가 클라이언트 측 암호화 (CSE) 데이터의 열기를 요청하면 Google Workspace에서 복호화를 위해 KACLS 엔드포인트 URL에 unwrap 요청을 전송합니다. 선택적 보안 검사(예: 경계 및 JWT 클레임 기반 검사) 외에도 KACLS는 다음 단계를 실행해야 합니다.
이메일 클레임에 대해 대소문자를 구분하지 않는 일치를 실행하여 승인 및 인증 토큰이 동일한 사용자를 위한 것인지 확인합니다.
인증 토큰에 선택적 google_email 클레임이 포함된 경우 대소문자를 구분하지 않는 접근 방식을 사용하여 승인 토큰의 이메일 클레임과 비교해야 합니다. 이 비교를 위해 인증 토큰 내에서 이메일 클레임을 사용하지 마세요.
인증 토큰에 선택적 google_email 클레임이 없는 시나리오에서는 인증 토큰 내의 이메일 클레임을 대소문자를 구분하지 않는 방법을 사용하여 승인 토큰의 이메일 클레임과 비교해야 합니다.
Google 계정과 연결되지 않은 이메일에 대해 Google에서 승인 토큰을 발급하는 시나리오에서는 email_type 클레임이 있어야 합니다.
이는 게스트 액세스 기능의 중요한 부분으로, KACLS가 외부 사용자에게 추가 보안 조치를 적용할 수 있는 유용한 정보를 제공합니다.
KACLS가 이 정보를 사용하는 방법의 예는 다음과 같습니다.
추가 로깅 요구사항을 적용합니다.
인증 토큰 발급자를 전용 게스트 IdP로 제한합니다.
인증 토큰에 추가 클레임을 요구합니다.
고객이 게스트 액세스를 구성하지 않은 경우 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과 일치해야 합니다.
승인 토큰의 role 클레임이 reader 또는 writer인지 확인합니다.
승인 토큰의 kacls_url 클레임이 현재 KACLS URL과 일치하는지 확인합니다. 이를 통해 내부자 또는 악성 도메인 관리자가 구성한 잠재적인 중간자 서버를 감지할 수 있습니다.
인증된 암호화 알고리즘을 사용하여 다음 부분을 복호화합니다.
데이터 암호화 키 (DEK)
승인 토큰의 resource_name 및 perimeter_id 값
추가 민감한 정보
승인 토큰과 복호화된 blob의 resource_name가 일치하는지 확인합니다.
인증 및 승인 클레임을 모두 사용하여 경계 검사를 실행합니다.
작업을 기록합니다. 여기에는 작업을 시작한 사용자, resource_name, 요청에 전달된 이유가 포함됩니다.
[null,null,["최종 업데이트: 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)."]]
