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

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

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

IAP는 다음과 함께 사용할 수 있습니다.

  • App Engine 표준 환경 및 App Engine 가변형 환경 앱
  • HTTP(S) 부하 분산 백엔드 서비스가 포함된 Compute Engine 인스턴스
  • Google Kubernetes Engine 컨테이너
  • HTTP(S) 부하 분산 백엔드 서비스가 포함된 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를 사용할 수 있나요?

예. IAP로 보호되는 리소스는 API가 사용 중지된 상태에서도 계속 액세스할 수 있지만 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)를 해결하려면 어떻게 해야 하나요?

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

  • 브라우저 기반 요청: 프로젝트별 분당 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 허용된 도메인에 속하지 않는 호스트 이름 관리자가 허용된 도메인 목록에 호스트 이름을 추가해야 합니다. 자세한 내용은 리소스 액세스 제한을 참고하세요.
429 요청 할당량 초과 요청 한도 (요청 유형당 분당 360,000개)에 도달했습니다. 합법적인 성장을 위해 필요한 경우 여러 프로젝트에 워크로드를 분산하거나, 클라이언트 측 요청 제한을 구현하거나, 지원팀에 문의하여 할당량을 늘리는 것이 좋습니다.
551 여러 위치에서 IAP 사용 설정 전달 규칙과 백엔드 서비스에서 모두 IAP를 사용 설정할 수는 없습니다. Compute Engine에서 사용 설정의 안내에 따라 한 위치에서 사용 중지합니다.
700, 701 직원 풀 제공업체 문제 직원 풀에 공급업체를 정확히 하나 구성합니다. 자세한 요구사항은 인력 풀 제한사항을 참고하세요.
705 Workforce Identity의 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에 문의하세요. 응답에서 클라이언트 보안 비밀번호를 삭제해야 합니다.