액세스 제어 문제 해결

이 문서를 사용하여 Identity and Access Management(IAM) 권한, 열 수준 액세스 제어, 고객 관리 암호화 키(CMEK), 정책 위반을 포함한 BigQuery 보안 및 권한 문제를 해결하세요. 액세스 제어 실패는 일반적으로 주 구성원이 작업을 실행하거나 리소스에 액세스할 때 Access Denied 또는 403 Forbidden 오류를 생성합니다.

일반적인 액세스 거부 오류

다음은 일반적인 액세스 거부 오류의 예시입니다.

  • Access Denied: Project PROJECT_ID: User does not have bigquery.jobs.create permission in project PROJECT_ID.
  • Access Denied: Project PROJECT_ID: User does not have bigquery.datasets.get permission on dataset DATASET.
  • User does not have permission to query table PROJECT_ID:DATASET.TABLE.
  • Access Denied: Table PROJECT_ID:DATASET.TABLE: User does not have permission to query table PROJECT_ID:DATASET.TABLE, or perhaps it does not exist.
  • Access Denied: User PRINCIPAL does not have permission to perform bigquery.tables.getData on resource 'projects/PROJECT_ID/datasets/DATASET/tables/TABLE'.

시작하기 전에

  • BigQuery 리소스에 대한 주 구성원의 액세스 문제를 해결하려면 필수 IAM 권한이 있는지 확인하세요.

문제에 관한 정보 수집하기

리소스 액세스 문제를 해결하는 첫 번째 단계는 누락된 권한, 액세스가 거부된 IAM 주 구성원, 주 구성원이 액세스하려고 시도한 리소스를 확인하는 것입니다.

오류 또는 작업 기록에서 정보 가져오기

주 구성원, 리소스, 권한에 대한 정보를 가져오려면 bq 명령줄 도구, API 응답 또는 Google Cloud 콘솔의 BigQuery에서 출력을 검사합니다.

예를 들어 권한이 부족한 상태에서 쿼리를 실행하려고 하면 Google Cloud 콘솔의 쿼리 결과 섹션에 있는 작업 정보 탭에 다음과 같은 오류가 표시됩니다.

쿼리 결과 섹션의 작업 정보 탭에 액세스 거부 오류가 표시됩니다.

오류를 검사하여 주 구성원, 리소스, 권한을 확인합니다.

경우에 따라 오류 메시지에서 직접 누락된 권한을 요청할 수 있습니다. 자세한 내용은 IAM 문서의 권한 오류 메시지를 참조하세요.

Cloud 감사 로그에서 정보 가져오기

오류 메시지가 일반적이거나 정보가 누락되었거나 백그라운드 프로세스에서 작업이 실패한 경우 Cloud 감사 로그 탐색기를 사용하여 오류에 대한 정보를 가져옵니다.

  1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

    로그 탐색기로 이동

    또는 탐색 메뉴에서 모니터링 > 로그 탐색기를 선택합니다.

  2. 로그 탐색기에서 로그 범위로 프로젝트 로그를 선택합니다.

  3. 쿼리 창에서 다음 쿼리를 입력하여 BigQuery 데이터 액세스 로그에서 권한 관련 오류를 가져옵니다.

    resource.type=("bigquery_resource" OR "bigquery_project" OR "bigquery_dataset") AND
logName=("projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access" OR
  "projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Factivity") AND
(protoPayload.status.message:"Access Denied" OR
  protoPayload.status.message:"Permission denied" OR
  protoPayload.status.code=7)

    PROJECT_ID를 프로젝트 ID로 바꿉니다.

  4. 쿼리 결과에서 실패한 작업에 해당하는 로그 항목을 펼칩니다.

  5. protoPayload 섹션에서 authorizationInfo 배열을 펼친 다음 authorizationInfo 배열의 각 노드를 펼칩니다.

    authorizationInfo 배열은 API 호출 중에 수행된 모든 권한 검사를 보여줍니다.

  6. 오류의 원인을 확인하려면 granted: false 항목을 찾습니다. granted: false 항목에는 다음 정보가 표시됩니다.

    • permission: 확인된 IAM 권한 문자열입니다. 예를 들면 bigquery.tables.getData입니다.
    • resource: 주 구성원이 액세스하려고 시도한 리소스의 정규화된 이름입니다. 예를 들면 projects/myproject/datasets/mydataset/tables/mytable입니다.
    • principalEmail (사용 가능한 경우): protoPayload.authenticationInfo에서 참조되며, 작업을 시도한 주 구성원입니다.

    권한, 리소스, principalEmail을 보여주는 protoPayload의 authorizationInfo 섹션

허용 정책에 정책 분석 도구 사용

허용 정책에 대한 정책 분석 도구를 사용하면 IAM 허용 정책에 따라 어떤 IAM 주 구성원이 어떤 BigQuery 리소스에 대해 어떤 액세스 권한을 갖는지에 관한 정보를 확인할 수 있습니다.

권한 오류에 대한 정보를 수집한 후에는 정책 분석 도구를 사용하여 주 구성원에게 필요한 액세스 권한이 없는 이유를 파악할 수 있습니다. 이 도구는 모든 관련 정책, Google 그룹스의 멤버십, 프로젝트, 폴더, 조직과 같은 상위 리소스의 상속을 분석합니다.

허용 정책에 대해 정책 분석 도구를 사용하려면 분석 쿼리를 만들고, 분석 범위를 지정한 후 쿼리를 실행합니다.

  1. Google Cloud 콘솔에서 정책 분석 도구 페이지로 이동합니다.

    정책 분석 도구로 이동

    또는 탐색 메뉴에서 IAM 및 관리자 > 정책 분석 도구를 선택합니다.

  2. 사용자 지정 쿼리 만들기를 클릭하세요.

  3. 쿼리 구성 페이지에서 이전에 수집한 정보를 입력합니다.

    1. 범위 선택 섹션의 쿼리 범위 선택 필드에서 현재 프로젝트가 표시되는지 확인하거나 찾아보기를 클릭하여 다른 리소스를 선택합니다.

    2. 쿼리 매개변수 설정 섹션에서 매개변수 1에 대해 주 구성원을 선택하고 주 구성원 필드에 사용자, 그룹 또는 서비스 계정의 이메일을 입력합니다.

    3. 파라미터 추가를 클릭합니다.

    4. 매개변수 2에서 권한을 선택하고 권한 필드에서 선택을 클릭하고 BigQuery 권한을 선택한 후 추가를 클릭합니다. 예를 들어 bigquery.tables.getData를 선택하세요.

    5. 파라미터 추가를 클릭합니다.

    6. 매개변수 3에서 리소스를 선택하고 리소스 필드에 정규화된 리소스 이름을 입력합니다. 리소스 이름에는 다음 예시와 같이 서비스 프리픽스가 포함되어야 합니다.

      • BigQuery 프로젝트: //cloudresourcemanager.googleapis.com/projects/PROJECT_ID
      • BigQuery 데이터 세트: //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET
      • BigQuery 테이블: //bigquery.googleapis.com/projects/PROJECT/datasets/DATASET/tables/TABLE

  4. 커스텀 쿼리 창에서 분석 > 쿼리 실행을 클릭합니다.

  5. 쿼리 결과를 살펴봅니다. 결과는 다음 중 하나일 수 있습니다.

    • 빈 목록 결과가 없으면 주 구성원에게 필요한 권한이 없음을 확인합니다. 올바른 권한을 제공하는 주 구성원에게 역할을 부여해야 합니다.
    • 하나 이상의 결과 분석 도구가 허용 정책을 찾으면 어떤 형태의 액세스 권한이 존재합니다. 각 결과에서 바인딩 보기를 클릭하여 주 구성원이 구성원인 리소스에 대한 액세스 권한을 제공하는 역할을 확인합니다. 정책 바인딩은 그룹 멤버십 또는 상속을 통해 액세스 권한이 부여되는지 또는 IAM 조건 또는 IAM 거부 정책에 의해 액세스가 거부되는지 여부를 보여줍니다.

필요한 권한을 부여하는 올바른 IAM 역할 찾기

주 구성원에게 충분한 액세스 권한이 없음을 확인한 후 다음 단계는 필요한 권한을 부여하는 적절한 사전 정의된 IAM 역할 또는 커스텀 IAM 역할을 찾는 것입니다. 선택하는 역할은 최소 권한의 원칙을 준수해야 합니다.

조직에서 커스텀 역할을 사용하는 경우 프로젝트 또는 조직에 생성된 모든 커스텀 역할을 나열하여 올바른 역할을 찾을 수 있습니다. 예를 들어 Google Cloud 콘솔의 역할 페이지에서 유형:커스텀으로 목록을 필터링하여 커스텀 역할만 볼 수 있습니다.

올바른 사전 정의된 IAM 역할을 찾으려면 다음 단계를 따르세요.

  1. BigQuery IAM 역할 및 권한 페이지의 BigQuery 권한 섹션을 엽니다.

  2. 권한 입력 검색창에 오류 메시지, 작업 기록 또는 감사 로그에서 가져온 권한을 입력합니다. 예를 들면 bigquery.tables.getData입니다.

    검색 결과에는 권한을 부여하는 사전 정의된 모든 BigQuery 역할이 표시됩니다.

  3. 최소 권한의 원칙 적용: 역할 목록에서 필요한 권한을 부여하는 가장 권한이 적은 역할을 선택합니다. 예를 들어 테이블 데이터를 쿼리할 수 있는 권한을 부여하기 위해 bigquery.tables.getData를 검색한 경우 BigQuery 데이터 뷰어는 해당 권한을 부여하는 최소 권한 역할입니다.

  4. 주 구성원에게 적절한 역할을 부여합니다. BigQuery 리소스에 IAM 역할을 부여하는 방법에 대한 자세한 내용은 IAM으로 리소스에 대한 액세스 제어를 참조하세요.

일반적인 액세스 거부 시나리오 문제 해결

작업이 403 accessDenied (Access Denied: RESOURCE_TYPE RESOURCE_ID: DETAILS)로 실패하면 앞의 일반적인 IAM 단계 외에 다음 일반적인 시나리오를 확인하세요.

  • 존재하지 않는 리소스 또는 위치 불일치 (or perhaps it does not exist). 오류 메시지가 or perhaps it does not exist로 끝나는 경우 주 구성원에게 데이터 세트 또는 프로젝트 메타데이터 권한(bigquery.tables.get 또는 bigquery.datasets.get)이 없기 때문에 BigQuery에서 테이블, 뷰 또는 루틴이 존재하는지 여부를 마스킹합니다. 프로젝트 ID, 데이터 세트 ID, 테이블 이름의 철자가 올바른지 확인하고 쿼리가 데이터 세트와 동일한 위치에서 실행되는지 확인합니다.

  • 승인된 뷰 및 루틴. 사용자가 승인된 뷰 또는 승인된 루틴을 쿼리할 때 사용자에게는 뷰 또는 루틴을 쿼리할 수 있는 권한이 필요하며 뷰 또는 루틴 자체는 소스 데이터 세트의 액세스 제어 목록 (ACL)에서 승인되어야 합니다. 기본 테이블에서 Access Denied로 인해 쿼리가 실패하면 뷰 또는 루틴 (또는 전체 데이터 세트를 승인된 데이터 세트로)을 소스 데이터 세트의 승인된 액세스 목록에 추가합니다. 뷰가 다른 뷰를 쿼리하는 경우 체인의 모든 뷰는 읽어오는 데이터 세트에 대해 승인되어야 합니다.

    승인된 뷰 또는 승인된 데이터 세트가 삭제되고 동일한 이름으로 다른 뷰 또는 데이터 세트가 생성된 경우 쿼리가 Access Denied로 인해 실패할 수 있습니다. 이 오류는 삭제된 항목이 최대 24시간 동안 남아 있을 수 있는 소스 데이터 세트의 승인된 액세스 목록에 이름이 계속 표시되는 경우에도 발생할 수 있습니다. Cloud 감사 로그를 확인하여 쿼리가 마지막으로 성공한 이후 체인의 승인된 뷰 또는 승인된 데이터 세트가 삭제되고 교체되었는지 확인합니다. 액세스 권한을 복원하려면 먼저 소스 데이터 세트의 승인된 액세스 목록에서 기존 항목을 삭제한 후 새 뷰 또는 데이터 세트를 다시 추가합니다. 이전 항목을 삭제하기 전에 새 뷰를 추가하면 Duplicate authorized views 오류가 발생할 수 있습니다.

    승인을 중단하지 않고 뷰를 수정하려면 뷰를 삭제하고 다시 만드는 대신 뷰의 SQL 쿼리를 업데이트합니다. 하지만 CREATE OR REPLACE 문 또는 routines.update 메서드를 사용하여 승인된 루틴을 수정하는 경우 루틴을 다시 승인해야 합니다.

  • VPC 서비스 제어. 조직에서 VPC 서비스 제어를 사용하는 경우 서비스 경계 경계를 넘는 요청은 403 accessDenied 또는 policyViolation로 인해 실패합니다. 실패 시점의 Cloud 감사 로그에서 오류 메시지의 vpcServiceControlsUniqueIdentifier 값을 검색하고 위반 분석기를 사용하여 인그레스 및 이그레스 규칙을 검사합니다. 사용할 로그 탐색기 쿼리는 조직 정책에 따라 요청이 금지됨을 참조하세요.

  • 기본 역할 (roles/owner, roles/editor, roles/viewer). 기본 프로젝트 역할에는 INFORMATION_SCHEMA.TABLE_STORAGE_USAGE_TIMELINE_BY_ORGANIZATION과 같은 뷰에 필요한 조직 수준 권한 또는 행 수준 액세스 정책이 있거나 있었던 테이블의 이전 데이터에 액세스하는 데 필요한 bigquery.rowAccessPolicies.overrideTimeTravelRestrictions과 같은 특수 권한이 포함되지 않습니다(시간 이동 및 행 수준 액세스 참조). 기본 역할에 의존하는 대신 사전 정의된 BigQuery IAM 역할을 부여합니다.

  • 일시적인 IAM 정책 덮어쓰기 (SetIamPolicy). 권한이 간헐적으로 작동한 후 실패하는 경우 관리자 활동 감사 로그에서 protoPayload.methodName=~"SetIamPolicy"를 검색하여 자동화된 스크립트 또는 코드형 인프라 파이프라인이 기존 정책 바인딩을 병합하는 대신 덮어쓰는지 확인합니다.

  • 외부 데이터 소스(Google Drive, Cloud Storage, BigLake):

    • Google Drive (Permission denied while getting Drive credentials). 사용자 또는 서비스 계정에 Google Drive 파일 또는 Google 시트에 대한 뷰어 액세스 권한을 부여하고, 호출자가 https://www.googleapis.com/auth/drive OAuth 범위를 제공하는지 확인하거나, 예약된 쿼리 사용자 인증 정보를 업데이트합니다.
    • Cloud Storage 및 BigLake 테이블 Cloud Storage 버킷에 대한 roles/storage.objectViewer을 사용자(표준 외부 테이블의 경우) 또는 BigLake 연결 서비스 계정 (BigLake 테이블의 경우)에 부여합니다.

  • 고객 관리 암호화 키(CMEK). 쿼리가 CMEK로 보호되는 테이블을 참조하는 경우 해당 Cloud KMS 키가 있고 사용 설정되어 있는지 확인합니다. 쿼리 또는 로드 작업이 Cloud KMS Error: Permission 'cloudkms.cryptoKeyVersions.useToEncrypt' denied (또는 useToDecrypt)로 실패하면 BigQuery 암호화 서비스 에이전트(bq-PROJECT_NUMBER@bigquery-encryption.)에 Cloud Key Management Service 키에 대한 roles/cloudkms.cryptoKeyEncrypterDecrypter 역할을 부여합니다. 암호화 및 복호화 권한 부여를 참조하세요. 다른 CMEK 오류는 고객 관리 암호화 키 문제 해결을 참조하세요.

  • 서비스 계정 가장 서비스 계정 가장을 사용하는 요청이 Permission 'iam.serviceAccounts.getAccessToken' denied로 실패하면 대상 서비스 계정에서 호출 주 구성원에게 roles/iam.serviceAccountTokenCreator을 부여합니다.

  • 열 수준 보안 (정책 태그) 및 행 수준 보안 쿼리 또는 DML 문이 Requires fineGrainedGet permission on the read columns 또는 User does not have permission to access data protected by policy tag로 실패하면 주 구성원에게 정책 태그에 대한 Data Catalog 세분화된 리더(roles/datacatalog.categoryFineGrainedReader) 역할을 부여하거나 SELECT 목록에서 보호된 열을 제외합니다. 열 수준 액세스 제어 권한 부족을 참조하세요. 테이블에서 행 수준 보안을 사용하는 경우 Google Cloud 콘솔에서 또는 bq ls --row_access_policies를 실행하여 활성 행 수준 액세스 정책을 검토합니다. 테이블 행 수준 액세스 정책 나열을 참조하세요.

  • IAM 및 메타데이터 전파 지연 새로 부여된 IAM 역할 및 데이터 세트 ACL 업데이트는 eventual consistency를 가지며 일반적으로 캐시 전체에 전파되는 데 몇 분 정도 걸립니다. 권한이 방금 부여된 경우 몇 분 정도 기다린 후 요청을 다시 시도하세요.

BigQuery 서비스 약관에 동의하지 않음

오류 문자열: BigQuery Terms of Service have not been accepted

이 HTTP 403 Forbidden 오류 (reason: termsOfServiceNotAccepted)는 BigQuery 서비스 약관에 동의하지 않은 경우에 발생합니다. IAM 권한 누락으로 인해 오류가 발생하지 않습니다. 데이터 세트 만들기 또는 데이터 로드와 같은 요청에 대해 반환될 수 있습니다.

이 문제를 해결하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 BigQuery 페이지로 이동합니다.

    BigQuery로 이동

  2. 시작 페이지가 표시되면 국가를 선택하고 서비스 약관 체크박스를 선택한 후 동의 및 계속을 클릭합니다. 자세한 내용은 BigQuery 샌드박스 사용 설정을 참조하세요.

서비스 약관에 동의한 후 요청을 다시 시도합니다.

정책 위반 오류 문제 해결

BigQuery에서 policyViolation 오류 이유와 함께 HTTP 403 PERMISSION_DENIED 오류가 수신되면 조직 정책, 데이터 경계 또는 VPC 서비스 제어로 인해 오류가 발생했음을 나타냅니다.

다음 섹션에서는 이 오류 원인과 관련된 가장 일반적인 오류 메시지, 원인, 해결 방법을 설명합니다.

조직의 정책에 따라 요청이 금지됨

오류 문자열: VPC Service Controls: Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: VPC_SERVICE_CONTROLS_UNIQUE_IDENTIFIER

진단

요청이 지정된 VPC 서비스 제어 경계 외부에 있는 네트워크 주소 또는 클라이언트에서 시작되었거나 요청이 작업공간에 정의된 인그레스 및 이그레스 규칙을 위반했습니다. 이는 쿼리가 여러 프로젝트에 걸쳐 있는 경우에 자주 발생합니다. 예를 들어 쿼리 결제 프로젝트가 데이터 프로젝트의 보안 경계 외부에 있습니다.

해결 방법

  1. 고유 ID를 찾습니다. 오류 메시지에 포함된 vpcServiceControlsUniqueIdentifier를 검색합니다. 이 ID를 사용하여 Google Cloud로그 탐색기를 필터링하여 이유에 대한 세부정보가 포함된 해당 VPC 서비스 제어 로그를 찾습니다.

    protoPayload.metadata.@type="type.googleapis.com/google.cloud.audit.VpcServiceControlAuditMetadata"
protoPayload.metadata.vpcServiceControlsUniqueId="VPC_SERVICE_CONTROLS_UNIQUE_IDENTIFIER"

    protoPayload.metadata.violationReason에서 violationReason 값을 찾습니다. 식별되면 로그 항목의 추가 세부정보를 살펴보고 기존 VPC 서비스 제어 문제 해결 가이드를 따릅니다. 또한 위반 분석기를 사용하는 것이 좋습니다.

  2. 프로젝트 간 결제를 수정합니다. 교차 프로젝트 쿼리의 경우 쿼리를 실행하는 결제 프로젝트가 경계 내에서 쿼리된 데이터와 동일한 경계에 있는지 확인합니다. 필요한 경우 Google Cloud 콘솔 프로젝트 선택기, bq 명령줄 도구의 --project_id 플래그 또는 API 또는 클라이언트 라이브러리 요청을 사용하여 규정을 준수하는 결제 프로젝트를 수동으로 지정합니다.

  3. 액세스 수준을 확인합니다. Access Context Manager를 사용하여 클라이언트 네트워크, IP 또는 사용자 계정이 허용되는지 확인합니다.Google Cloud 콘솔에는 보호된 환경에 대한 사용자 액세스를 허용하도록 특별히 구성된 인그레스 규칙이 필요합니다.

VPC 서비스 제어가 사용 설정된 프로젝트의 경우 Google Drive로 내보내기가 차단됩니다.

오류 문자열: Export to Google Drive is blocked for projects with VPC-SC enabled

진단

Google Drive는 VPC 서비스 제어를 지원하지 않습니다. Google Drive는 보안 경계를 적용할 수 없으므로 BigQuery는 VPC 서비스 제어 경계 내에서 발생하는 모든 요청에 대해 Google Drive로의 API 추출 내보내기를 자동으로 사용 중지하여 데이터 무단 반출을 방지합니다.

해결 방법

Google Drive로 직접 내보내는 대신 동일한 VPC 서비스 제어 경계 내에 있는 Cloud Storage 버킷으로 쿼리 결과를 추출하거나 결과를 로컬 파일로 저장합니다.

VPC 서비스 제어가 사용 설정된 프로젝트에서 Google Drive 외부 테이블이 차단됨

오류 문자열: Google Drive external tables are blocked for projects with VPC-SC enabled

진단

기본적으로 VPC 서비스 제어는 Google Drive 외부 테이블 (예: 연결된 시트) 쿼리를 차단하지 않습니다. 하지만 이 오류는 Google Cloud 조직에서 기본 허용 동작을 재정의하기 위해 프로젝트에 엄격한 차단 구성을 적용하도록 명시적으로 요청하여 VPC 서비스 제어 경계 내에서 Google Drive 데이터에 대한 인바운드 쿼리를 방지하기 때문에 발생합니다. Google Cloud

해결 방법

Google 시트 또는 Google Drive 파일의 데이터를 외부 제휴 테이블로 동적으로 쿼리하는 대신 VPC 서비스 제어 경계 내의 표준 BigQuery 테이블로 직접 가져옵니다. 또는 내부 Cloud 관리자에게 문의하여 조직의 데이터 내보내기 경계에 대해 논의하세요.

프로젝트에서 Google Drive로 내보내기가 차단되었습니다.

오류 문자열: Export to Google Drive is blocked for your project.

진단

VPC 서비스 제어 경계가 없더라도 Google Cloud 관리자가 Google Drive에 대한 모든 데이터 추출 기능을 거부하는 특정하고 엄격한 조직 구성을 프로젝트에 적용하도록 요청했습니다.

해결 방법

Cloud Storage 버킷 또는 로컬 파일과 같은 대체 추출 대상을 선택하거나 내부 클라우드 관리자에게 문의하여 조직의 데이터 내보내기 경계에 대해 논의하세요.

위치가 조직 정책 제약 조건을 위반함

오류 문자열: LOCATION violates constraint CONSTRAINT_NAME on the resource projects/PROJECT_ID 또는 LOCATION violates constraint CONSTRAINT_NAME on the resource projects/PROJECT_ID/datasets/DATASET_ID

진단

클라우드 관리자가 리소스를 만들거나 분석할 수 있는 위치를 정확하게 제한하도록 조직 정책 제약 조건을 구성했습니다. 이 오류는 일반적으로 다음과 같은 경우에 발생합니다.

  • 승인되지 않은 지리적 리전에서 데이터 세트 만들기 (예: constraints/gcp.resourceLocations에 의해 제한됨)
  • 허용되지 않는 경우 (예: constraints/bigquery.disableBQOmniAWS 또는 constraints/bigquery.disableBQOmniAzure에 의해 차단됨) 외부 클라우드에서 BigQuery Omni를 사용하려고 시도합니다.

해결 방법

  1. 오류 메시지에 제공된 정확한 CONSTRAINT_NAME를 확인하여 차단되는 작업을 파악합니다.
  2. 데이터에 대해 차단되지 않은 다른 리전을 선택하거나Google Cloud 조직 관리자와 협력하여 폴더 또는 조직 수준에서 조직 정책을 검토하세요. 자세한 내용은 리소스 위치 구조화 및 정의를 참조하세요.

인증되지 않은 오류 문제 해결

BigQuery에서 unauthenticated 오류 이유와 함께 HTTP 401 Unauthorized (gRPC UNAUTHENTICATED) 오류가 수신되면 요청에 유효한 사용자 인증 정보가 없거나, OAuth 2.0 액세스 토큰이 만료되었거나, 호출자가 지정된 ID로 인증할 수 없는 것입니다.

다음 섹션에서는 가장 일반적인 unauthenticated 시나리오, 원인, 해결 방법을 설명합니다.

사용자 인증 정보가 잘못되었거나 만료됨

오류 문자열:

  • Invalid credential
  • User credential was invalid.
  • Credentials expired
  • Credentials missing required scope.
  • Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.

진단

요청과 함께 제공된 액세스 토큰, 서비스 계정 키 또는 애플리케이션 기본 사용자 인증 정보 (ADC)가 만료되었거나 취소되었거나 필수 OAuth 2.0 범위가 누락되었습니다. 이 오류는 네트워크 시간 프로토콜 (NTP) 시간에서 벗어난 시스템 시계로 요청이 서명된 경우에도 발생합니다.

해결 방법

  • 사용자 인증 정보를 새로고침합니다. 로컬 개발 환경에서 인증하는 경우 gcloud auth application-default login (ADC의 경우) 또는 gcloud auth login을 실행하여 새 토큰을 가져옵니다.
  • 서비스 계정 키와 OAuth 범위를 확인합니다. 애플리케이션에서 GOOGLE_APPLICATION_CREDENTIALS를 사용하는 경우 변수가 취소되지 않은 유효한 JSON 키 파일을 가리키는지, 서비스 계정이Google Cloud 콘솔에서 사용 설정되어 있는지, 사용자 인증 정보에 필요한 https://www.googleapis.com/auth/bigquery 또는 https://www.googleapis.com/auth/cloud-platform 범위가 포함되어 있는지 확인합니다.
  • 현재 클라이언트 라이브러리를 사용하고 시스템 시계를 동기화합니다. OAuth 2.0 토큰 새로고침 및 제휴 사용자 인증 정보가 자동으로 처리되도록 BigQuery 클라이언트 라이브러리 또는 ODBC 또는 JDBC 드라이버를 최신 버전으로 업데이트합니다. 또한 호스트 머신의 시스템 시계가 NTP를 사용하여 동기화되었는지 확인합니다.

최종 사용자 인증 정보 또는 서비스 계정 가장 권한 누락

오류 문자열:

  • Current user can not act as user for service account SERVICE_ACCOUNT_EMAIL
  • No end user credentials found when accessing PROJECT_ID:DATASET_ID.TABLE_ID. Please use end user credentials to call BigQuery APIs.

진단

작업 또는 연속 쿼리가 호출자에게 가장할 권한이 없는 커스텀 서비스 계정으로 실행되도록 구성되었거나, BigQuery가 대화형 사용자 ID에 대한 액세스를 평가할 수 있도록 대상 테이블 또는 보안 정책에 최종 사용자 인증 정보 (EUC)가 필요합니다.

해결 방법

  • 서비스 계정 가장 권한을 부여합니다. 커스텀 서비스 계정으로 구성된 연속 쿼리 또는 작업을 실행할 때 호출자에게 해당 서비스 계정에 대한 서비스 계정 사용자 역할(roles/iam.serviceAccountUser, iam.serviceAccounts.actAs 권한 포함)을 부여합니다. 서비스 계정을 가장하거나 제휴 사용자 인증 정보를 단기 토큰으로 교환할 때 호출자에게 대상 서비스 계정에 대한 서비스 계정 토큰 생성자 역할(roles/iam.serviceAccountTokenCreator)을 부여합니다.
  • 최종 사용자 인증 정보로 인증합니다. 대상 리소스에 최종 사용자 인증 정보가 필요한 경우 독립형 서비스 계정 사용자 인증 정보가 아닌 대화형 사용자의 OAuth 2.0 사용자 인증 정보를 사용하여 요청을 인증합니다 (예: gcloud auth application-default login 실행 또는 BI 도구에서 사용자 OAuth 구성).
  • VPC 서비스 제어 인그레스 및 이그레스 규칙을 확인합니다. 요청이 VPC 서비스 제어 경계를 넘는 경우 경계의 인그레스 및 이그레스 규칙이 호출자 ID와 대상 리소스를 허용하는지 확인합니다.

계정이 제한, 정지 또는 삭제됨

오류 문자열:

  • The account was restricted due to REASON
  • Account deleted

진단

요청을 실행하는 Google 계정 또는 Google Workspace 계정이 관리자 또는 계정 보안 정책에 의해 정지, 사용 중지, 제한 또는 삭제되었습니다.

해결 방법

Google Workspace 또는 Cloud ID 관리자에게 문의하여 Google 관리 콘솔에서 계정 상태를 검토하고 사용자 계정을 복원하거나 정지를 해제하거나 활성 서비스 계정으로 인증하도록 워크로드를 업데이트하세요.

열 수준 액세스 제어 문제 해결

다음 섹션에서는 열 수준 액세스 제어 및 Data Catalog 정책 태그 관련 문제를 해결하는 방법을 설명합니다.

Data Catalog 역할을 볼 수 없습니다.

Data Catalog 세분화된 권한의 리더와 같은 역할을 볼 수 없는 경우 프로젝트에서 Data Catalog API를 사용 설정하지 않았을 수 있습니다. Data Catalog API를 사용 설정하는 방법은 시작하기 전에를 참조하세요. Data Catalog API를 사용 설정하고 몇 분 후에 Data Catalog 역할이 표시됩니다.

분류 페이지를 볼 수 없습니다.

Google Cloud 콘솔에서 정책 태그 분류 페이지를 보려면 추가 권한이 필요합니다. 예를 들어 Data Catalog 정책 태그 관리자 역할은 분류 페이지에 액세스할 수 있습니다.

정책 태그를 적용했지만 작동하지 않는 것 같습니다.

액세스 권한이 없는 계정에 대한 쿼리 결과가 계속 수신되는 경우 계정이 캐시된 결과를 수신하고 있을 수 있습니다. 특히 이전에 쿼리를 성공적으로 실행한 후 정책 태그를 적용한 경우 쿼리 결과 캐시에서 결과를 가져올 수 있습니다. 기본적으로 쿼리 결과는 24시간 동안 캐시됩니다. 결과 캐시를 사용 중지하면 쿼리가 즉시 실패합니다. 캐싱에 대한 자세한 내용은 열 수준 액세스 제어 영향을 참조하세요.

일반적으로 IAM 업데이트가 적용되기까지 약 30초가 걸립니다. 정책 태그 계층 구조의 변경사항이 적용되려면 최대 30분이 걸릴 수 있습니다.

열 수준 보안이 설정된 테이블에서 읽을 권한이 없습니다.

조직, 폴더, 프로젝트, 정책 태그와 같은 서로 다른 수준에서 세분화된 리더 역할 또는 마스킹된 리더 역할이 필요합니다. 세분화된 리더 역할은 원시 데이터 액세스 권한을 부여하고 마스킹된 리더 역할은 마스킹된 데이터에 대한 액세스 권한을 부여합니다. IAM 정책 문제 해결 도구를 사용하여 프로젝트 수준에서 이 권한을 확인할 수 있습니다.

정책 태그 분류에서 세분화된 액세스 제어를 설정했지만 사용자가 보호된 데이터를 볼 수 있음

이 문제를 해결하려면 다음 세부정보를 확인하세요.

  • BigQuery 보안 센터의 정책 태그 분류 페이지에서 액세스 제어 적용 전환 버튼이 사용 위치에 있는지 확인합니다.

  • 쿼리가 캐시된 쿼리 결과를 사용하지 않는지 확인합니다. bq 명령줄 도구를 사용하여 쿼리를 테스트하는 경우 --nouse_cache 플래그를 사용하여 쿼리 캐시를 중지합니다. 예를 들면 다음과 같습니다.

    bq query --nouse_cache --use_legacy_sql=false "SELECT * EXCEPT (customer_pii) FROM my_table;"

프로젝트 마이그레이션 고려사항

정책 태그와 분류는 특정 Google Cloud 조직 내에 있으며 프로젝트가 새 조직으로 마이그레이션될 때 자동으로 다시 연결되지 않습니다. 열 수준 액세스 제어에 정책 태그를 사용하는 프로젝트를 다른 조직으로 마이그레이션하면 다음 문제가 발생합니다.

  • 마이그레이션된 프로젝트 내의 Google Cloud 콘솔에서 정책 태그를 더 이상 관리할 수 없습니다.
  • 이전된 프로젝트의 새 열에는 이러한 정책 태그를 적용할 수 없습니다.
  • 기존 열 수준 액세스 제어가 계속 적용되는 것처럼 보일 수 있지만 관리 목적으로 원래 조직의 소스 분류에 대한 링크가 끊어집니다.

이 문제를 해결하려면 Google Cloud 지원팀에서 수동으로 개입하여 분류를 새 조직과 다시 연결해야 합니다. 정책 태그가 있는 프로젝트를 마이그레이션하고 이러한 문제가 발생하면 Cloud Customer Care에 문의하세요.

데이터 거버넌스 태그 문제 해결

다음 섹션에서는 데이터 거버넌스 태그를 사용하여 열에 대한 액세스를 제어할 때 발생하는 일반적인 문제를 해결하는 방법을 설명합니다.

태그 이름의 형식이 잘못됨

태그를 만들 때 닉네임(예: ssn)을 정의합니다. 하지만 스키마의 열에 태그를 연결하거나 조건에서 태그를 사용하는 경우 태그 키는 네임스페이스 형식(PROJECT_ID/TAG_KEY 또는 ORGANIZATION_ID/TAG_KEY)을 사용해야 하지만 태그 값은 여전히 닉네임을 사용합니다. 태그 키의 닉네임만 제공하면 Invalid tagKey 또는 Invalid tagValue 오류가 발생합니다.

프로젝트 간 정책 적용

기본적으로 테이블 프로젝트의 데이터 정책만 평가됩니다. 기본 데이터 정책 프로젝트가 조직 수준에서 구성되지 않는 한 다른 프로젝트의 정책은 적용되지 않습니다. 교차 프로젝트 정책 구성 및 평가에 대한 자세한 내용은 기본 데이터 정책 프로젝트 구성을 참조하세요.

고객 관리 암호화 키 문제 해결

다음 목록에서는 Cloud Key Management Service에서 고객 관리 암호화 키(CMEK)를 사용할 때 발생하는 일반적인 오류와 권장 해결 방법을 설명합니다.

오류: Please grant Cloud KMS CryptoKey Encrypter/Decrypter role
해결 방법: 프로젝트와 연결된 BigQuery 서비스 계정에 지정된 Cloud KMS 키로 작업을 수행하기 위한 IAM 권한이 부족합니다. 필요한 IAM 권한을 부여하려면 오류 메시지 또는 암호화 및 복호화 권한 부여의 안내를 따르세요.
오류: Existing table encryption settings don't match encryption settings specified in the request
해결 방법: 이 오류는 대상 테이블의 암호화 설정이 사용자 요청의 암호화 설정과 일치하지 않을 때 발생합니다. 이 문제를 해결하려면 TRUNCATE 쓰기 방식을 사용하여 테이블을 바꾸거나 다른 대상 테이블을 지정하세요.
오류: This region is not supported
해결 방법: Cloud KMS 키의 리전이 대상 테이블의 BigQuery 데이터 세트 리전과 일치하지 않습니다. 이 문제를 해결하려면 데이터 세트와 일치하는 리전의 키를 선택하거나 키 리전과 일치하는 데이터 세트에 데이터를 로드하세요.
오류: Your administrator requires that you specify an encryption key for queries in project PROJECT_ID.
해결 방법: 조직 정책으로 인해 리소스를 만들거나 쿼리를 실행할 수 없습니다. 이 정책에 대한 자세한 내용은 모든 리소스에 CMEK 요구를 참조하세요.
오류: Your administrator prevents using KMS keys from project KMS_PROJECT_ID to protect resources in project PROJECT_ID.
해결 방법: 조직 정책으로 인해 리소스를 만들거나 쿼리를 실행할 수 없습니다. 이 정책에 대한 자세한 내용은 BigQuery 프로젝트의 Cloud KMS 키 제한을 참조하세요.

다음 단계