자주 묻는 질문(FAQ) 및 문제 해결

이 문서에는 IAP(Identity-Aware Proxy)에 대한 자주 묻는 질문(FAQ)이 포함되어 있습니다.

IAP로 어떤 앱을 보호할 수 있나요?

IAP는 다음 항목에 사용할 수 있습니다.

  • App Engine 표준 환경 및 App Engine 가변형 환경 앱
  • HTTP(S) 부하 분산 백엔드 서비스가 포함된 Compute Engine 인스턴스
  • Google Kubernetes Engine 컨테이너
  • HTTP(S) 부하 분산 백엔드 서비스가 포함된 Cloud Run 앱
  • 클릭 한 번으로 Cloud Run을 사용하고 부하 분산 백엔드 서비스가 없는 경우

IAP는 Cloud CDN과 함께 사용할 수 없습니다.

앱에 로그인한 후 URL 끝에 #이 표시되는 이유는 무엇인가요?

일부 브라우저 및 특정 조건에서는 인증 후 URL에 #이 추가될 수 있습니다. 이것은 정상 동작이며, 로그인할 때 어떤 문제도 일으키지 않습니다.

요청이 실패하고 405 Method Not Allowed이 반환되는 이유는 무엇인가요?

일반적으로 요청에 쿠키가 연결되지 않은 경우 발생합니다. JavaScript 메서드는 기본적으로 쿠키를 연결하지 않습니다.

요청 메서드에 따라 접근 방식이 달라야 합니다.

  • XMLHttpRequest의 경우 withCredentials을 true로 설정
  • Fetch API의 경우 credentials을 include 또는 same-origin로 설정합니다.

세션 관련 오류 처리에 대한 내용은 IAP 세션 관리를 참고하세요.

302 Redirect 대신 HTTP 401 Unauthorized가 표시되는 이유는 무엇인가요?

IAP는 클라이언트가 리디렉션을 처리하도록 구성된 경우에만 302 Redirect를 전송합니다.

리디렉션 지원을 나타내려면 요청 헤더에 HTTP Accept="text/html,*/*"을 추가하세요.

POST 요청이 리디렉션을 트리거하지 않는 이유는 무엇인가요?

브라우저는 POST 요청에 대한 응답으로 리디렉션되지 않습니다. 대신 IAP는 401 Unauthorized 상태 코드를 반환합니다.

IAP 보안 리소스에 대한 POST 요청의 경우 다음 중 하나를 포함합니다.

API를 사용 중지한 경우 IAP를 사용할 수 있나요?

예. API가 사용 중지된 경우에도 IAP로 보호되는 리소스에 액세스할 수 있지만 IAM 권한을 수정할 수는 없습니다.

소유자 역할을 가진 사용자가 TCP에 IAP를 사용하지 못하도록 제한하려면 어떻게 해야 하나요?

가능한 한 소유자 (roles/owner) 역할 대신 더 세부적인 권한을 사용하는 것이 좋습니다. 자세한 내용은 IAM 권장사항을 참고하세요.

이러한 조치를 취할 수 없는 경우 방화벽 규칙을 사용하여 TCP에 대한 IAP를 차단할 수 있습니다.

TCP용 IAP는 어떤 도메인을 사용하나요?

IAP는 Google 소유의 다음 도메인을 사용합니다.

Server Error 오류가 발생하는 이유는 무엇인가요?

다음과 같은 메시지가 표시되는 경우

The server encountered a temporary error and could not complete your request. Please try again in 30 seconds.

방화벽이 부하 분산기 IP를 차단하고 있을 수 있습니다.

방화벽이 130.211.0.0/22 및 35.191.0.0/16의 트래픽을 허용하는지 확인합니다. 이러한 IP가 백엔드에 도달할 수 없으면 애플리케이션에 액세스할 수 없습니다.

특정 VM에 대한 IAP TCP 연결의 경우 VM이 35.235.240.0/20 범위의 연결을 허용하는지도 확인합니다.

간헐적인 내부 서버 오류가 발생하는 이유는 무엇인가요?

An internal server error occurred while authorizing your request. Error code X와 같은 메시지는 백엔드 실패를 나타냅니다.

오류 코드 1, 30, 62, 63, 64 또는 703은 일반적으로 일시적인 문제를 반영합니다. 재시도를 위해 지수 백오프를 구현합니다.

할당량 초과 오류(오류 코드 429)를 해결하려면 어떻게 해야 하나요?

애플리케이션이 IAP의 요청 한도를 초과하면 오류 코드 429가 발생합니다. 서비스는 별도의 할당량을 적용합니다.

  • 브라우저 기반 요청: 프로젝트별 분당 360,000개
  • 프로그래매틱 요청: 프로젝트별 분당 360,000개

프로그래매틱 요청은 AUTHORIZATION 또는 PROXY-AUTHORIZATION 헤더를 포함하고 IAP 쿠키는 포함하지 않는 요청입니다. 다른 모든 요청 (사용자 인증 정보가 없는 요청 포함)은 브라우저 요청으로 간주됩니다.

이러한 한도는 프로젝트의 모든 IAP 보호 리소스에 합산하여 적용됩니다.

할당량 관련 오류가 발생하는 경우 다음 해결 방법을 고려하세요.

  • 프로덕션에서 부하 테스트를 피하고 IAP를 우회하는 대체 네트워크 경로 사용
  • 서비스 간 트래픽의 경우 지수 백오프를 구현하여 429 오류를 적절하게 처리하세요.
  • 트래픽이 많은 애플리케이션을 여러 프로젝트에 분산
  • API 기반 애플리케이션에 Apigee 또는 유사한 API 게이트웨이 솔루션 사용
  • 자연 성장으로 인해 문제가 발생하는 경우 할당량 증가를 위해 Google Cloud 지원팀에 문의하세요.

오류 코드

다음 표에는 IAP 구성 및 사용 시 반환되는 일반적인 오류 코드와 메시지가 나와 있습니다.

오류 코드 설명 문제 해결
7 OAuth 클라이언트 ID 또는 보안 비밀이 비어 있음 사용자 인증 정보 페이지를 방문하여 클라이언트 ID와 보안 비밀번호를 확인하세요. 설정이 올바른 것으로 보이지만 작동하지 않는 경우 API 메서드를 사용하여 설정을 확인하고 (Compute Engine의 경우 GET, App Engine의 경우 GET) PATCH로 재설정합니다.
9 OAuth 리디렉션 실패 자동으로 기록된 내부 오류입니다. 고객님이 취하실 별도의 조치는 없습니다.
9 (경로 재작성 규칙 포함) OAuth 리디렉션 실패 부하 분산기의 경로 재작성 규칙으로 인해 OAuth가 완료되지 않습니다. 부하 분산기 뒤에 있는 모든 백엔드가 동일한 OAuth 클라이언트 ID를 사용하고 있는지 확인합니다. gcloud compute backend-services update 명령어를 사용하여 이를 업데이트할 수 있습니다.
9 (경로 라우팅 규칙 포함) OAuth 리디렉션 실패 각 경로의 두 버전 (후행 슬래시가 있는 버전과 없는 버전)에 대해 경로 규칙 변형을 만들고 동일한 백엔드로 연결합니다. 예를 들어 /path/ 및 /path에 대한 규칙을 모두 포함합니다.
11 OAuth 클라이언트 ID가 잘못 구성됨 사용자 인증 정보 페이지에서 클라이언트 ID와 보안 비밀번호를 확인합니다. 설정이 올바른 것으로 보이지만 작동하지 않는 경우 API 메서드를 사용하여 설정을 확인하고 (Compute Engine의 경우 GET, App Engine의 경우 GET) PATCH로 재설정합니다.
13 잘못된 OIDC 토큰 사용자 인증 정보 페이지로 이동하여 클라이언트 ID가 삭제되었거나 잘못 수정되지 않았는지 확인합니다.
51 브라우저에 연결 풀링 지원이 없음 최종 사용자에게 브라우저를 최신 버전으로 업데이트하도록 요청합니다. 연결 요구사항에 대한 자세한 내용은 리소스 액세스 제한을 참고하세요.
52 호스트 이름/SSL 인증서 불일치 시스템 관리자가 호스트 이름과 일치하도록 SSL 인증서를 업데이트해야 합니다. 안내는 리소스 액세스 제한을 참고하세요.
52 (기본 인증서 맵 항목 포함) 호스트 이름/SSL 인증서 불일치 IAP는 기본 인증서 맵 항목을 지원하지 않습니다. 각 인증서를 올바른 호스트 이름에 매핑하려면 별도의 항목을 사용하세요. 자세한 내용은 인증서 맵 항목 만들기를 참고하세요.
53 허용된 도메인에 없는 호스트 이름 관리자가 허용된 도메인 목록에 호스트 이름을 추가해야 합니다. 자세한 내용은 리소스 액세스 제한을 참고하세요.
253, HTTP 429 요청 할당량 초과 요청 한도 (요청 유형별로 분당 360,000개)에 도달했습니다. 여러 프로젝트에 워크로드를 분산하거나, 클라이언트 측 요청 제한을 구현하거나, 정당한 성장에 필요한 경우 지원팀에 문의하여 할당량 증가를 요청하세요.
551 여러 위치에서 IAP 사용 설정 전달 규칙과 백엔드 서비스 모두에서 IAP를 사용 설정할 수는 없습니다. Compute Engine 사용 설정의 안내에 따라 한 위치에서 사용 중지합니다.
700, 701 직원 풀 제공업체 문제 직원 풀에 공급업체를 정확히 하나 구성합니다. 자세한 요구사항은 직원 풀 제한사항을 참고하세요.
705 직원 ID의 OAuth 클라이언트 ID가 누락됨 전체 설정 프로세스를 따릅니다. 먼저 OAuth 클라이언트 ID를 만들고 IAP 설정을 업데이트합니다.
708 직원 풀 이름이 잘못되었습니다. 직원 풀이 존재하고 올바른 형식(locations/global/workforcePools/WORKFORCE_POOL_ID)을 사용하는지 확인합니다.
4003 연결 또는 방화벽 문제 VM 프로세스가 실행 중이고 예상 포트에서 리슨 중인지 확인합니다. 또한 방화벽 규칙이 해당 포트에서 연결을 허용하는지 확인합니다.
4010 대상에 의해 연결이 닫힘 VM을 재설정합니다. 문제가 계속되면 auth.log (일반적으로 /var/log/에 있음)를 검사하거나 직렬 콘솔을 사용하여 자세히 진단하세요.
4033 권한, 존재, VM 상태 문제 IAP 페이지를 통해 리소스에 터널 사용자 역할이 할당되어 있는지 확인하고 VM이 존재하며 실행 중인지 확인합니다.
4047 인스턴스가 존재하지 않거나 중지됨 VM의 전원이 켜져 있고 시작 시퀀스가 완전히 완료되었는지 확인합니다.

문제를 해결할 수 없거나 이 페이지에 나와 있는 오류가 없는 경우에는 오류에 대한 설명과 API에 대한 GET 호출에서 받은 응답에 대해 Cloud Customer Care에 문의하세요. 응답에서 클라이언트 보안 비밀번호를 삭제해야 합니다.