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

이 문서에서는 IAP(Identity-Aware Proxy)에 대한 문제 해결 안내와 자주 묻는 질문(FAQ)의 답변을 제공합니다.

웹 로그인 문제 해결

로그인 중 또는 애플리케이션에 액세스할 때 오류가 발생하는 경우 브라우저의 네트워크 트래픽을 검사하면 문제를 진단하는 데 도움이 될 수 있습니다.

네트워크 트래픽 검사

  1. 브라우저에서 새 시크릿 (Chrome) 또는 비공개 창을 엽니다.
  2. 브라우저의 개발자 도구를 열고 네트워크 탭으로 이동합니다.
  3. 리디렉션 중에 모든 요청을 캡처하려면 로그 보존 옵션을 선택합니다.
  4. 문제가 발생하는 URL로 이동하여 문제를 재현합니다.
  5. 로그의 네트워크 요청을 검토하여 오류가 발생한 위치를 확인합니다.

네트워크 트래픽 분석

IAP로 보호되는 애플리케이션에 액세스하면 로그인 페이지로 리디렉션됩니다. ID 공급업체로 인증이 완료되면 IAP 쿠키가 발급되고 애플리케이션으로 리디렉션되기 전에 인증을 완료하기 위해 https://iap.googleapis.com 도메인에 요청이 전송됩니다.

오류가 발생하는 도메인을 기준으로 오류를 해결할 수 있습니다.

  • iap.googleapis.com의 오류: iap.googleapis.com 도메인에서 오류가 발생하면 페이지에 자세한 오류 메시지가 표시됩니다. 오류가 OAuth 클라이언트 문제와 같은 IAP 설정과 관련된 경우 설정을 조정합니다. 해결 방법을 모르는 클라이언트 오류가 발생하거나 서버 오류가 표시되면 Google Cloud 지원 티켓을 엽니다.
  • 애플리케이션 도메인의 오류: IAP로 보호되는 애플리케이션 도메인으로 리디렉션된 후 오류가 발생하면 오류 코드가 표시됩니다. 일반적인 오류에 대한 자세한 내용은 오류 코드 섹션을 참조하세요. 문제를 해결할 수 없는 경우 Google Cloud 지원 티켓을 엽니다.

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가 반환되는 이유는 무엇인가요?

이 현상은 일반적으로 쿠키가 요청에 연결되지 않을 때 발생합니다. 자바스크립트 메서드는 기본적으로 쿠키를 연결하지 않습니다.

요청 메서드마다 접근 방식이 다릅니다.

  • 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은 일반적으로 일시적인 문제를 반영합니다. 재시도를 위해 지수 백오프를 구현합니다.

Identity Platform 오류 (오류 코드 38)를 수정하는 방법

오류 코드 38은 외부 ID의 Identity Platform 인증 URL이 IAP에서 올바르게 구성되지 않았음을 나타냅니다.

URL을 찾으려면 다음 단계를 따르세요.

  1. IAP 페이지로 이동합니다.

    IAP로 이동

  2. 애플리케이션 탭을 클릭합니다.

  3. 리소스 열에서 애플리케이션을 찾아 체크박스를 선택합니다.

  4. 인증 URL 또는 로그인 URL에서 URL이 올바른지 확인합니다.

IAP에서 외부 ID를 사용하는 방법을 알아보려면 외부 ID로 사용자 인증을 참조하세요.

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

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

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

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

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

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

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

Identity Platform을 사용하는 IAP의 로그인 문제 또는 예기치 않은 동작

Identity Platform과 함께 서드 파티 ID 공급업체 (IdP)를 사용하는 경우 ID 토큰의 대규모 클레임 데이터로 인해 IAP 세션 쿠키가 브라우저 크기 한도 (일반적으로 약 4KB)를 초과할 수 있습니다. IAP는 이러한 클레임을 포함한 세션 정보를 브라우저 쿠키에 저장합니다.

세션 쿠키 크기 한도를 초과하면 로그인 실패 또는 무한 로그인 루프가 발생할 수 있습니다. 이러한 문제를 방지하려면 다음 조치를 고려해 보세요.

  • 클레임 줄이기: Identity Platform에 필수 클레임만 전송하도록 서드 파티 IdP를 구성합니다. 토큰에 포함된 클레임의 크기와 수를 최소화합니다.

  • 쿠키 크기 검사: 브라우저 개발자 도구를 사용하여 애플리케이션 도메인에 설정된 쿠키의 크기를 확인합니다. 쿠키 크기와 관련된 경고, 특히 IAP 관련 쿠키에 대한 경고를 찾습니다.

  • 최소 클레임 테스트: 가능한 가장 작은 클레임 집합을 전송하도록 IdP를 일시적으로 구성합니다. 이렇게 하면 문제가 해결되고 쿠키 크기 제한이 근본 원인임을 확인할 수 있습니다.

오류 코드

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

오류 코드 설명 문제 해결
7 OAuth 클라이언트 ID 또는 보안 비밀번호가 비어 있음 사용자 인증 정보 페이지로 이동하여 클라이언트 ID와 보안 비밀번호를 확인합니다. 올바르게 표시되지만 작동하지 않는 경우 API 메서드를 사용하여 설정을 확인하고 (GET Compute Engine의 경우, GET App Engine의 경우) PATCH로 재설정합니다.
9 OAuth 리디렉션 실패 내부 오류이며 자동으로 로깅되었습니다. 고객님이 취하실 별도의 조치는 없습니다.
9 (경로 재작성 규칙 포함) OAuth 리디렉션 실패 부하 분산기의 경로 재작성 규칙으로 인해 OAuth가 완료되지 않습니다. 부하 분산기 뒤에 있는 모든 백엔드가 동일한 OAuth 클라이언트 ID를 사용하는지 확인합니다. gcloud compute backend-services update 명령어를 사용하여 업데이트할 수 있습니다.
9 (경로 라우팅 규칙 포함) OAuth 리디렉션 실패 각 경로의 두 버전 (후행 슬래시 포함 및 제외)에 대한 경로 규칙 변형을 만들고 동일한 백엔드로 전달합니다. 예를 들어 /path/ 및 /path 모두에 대한 규칙을 포함합니다.
11 OAuth 클라이언트 ID가 잘못 구성됨 사용자 인증 정보 페이지에서 클라이언트 ID와 보안 비밀번호를 확인합니다. 올바르게 표시되지만 작동하지 않는 경우 API 메서드를 사용하여 설정을 확인하고 (GET Compute Engine의 경우, GET App Engine의 경우) 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에 문의하세요. 응답에서 클라이언트 보안 비밀번호를 삭제해야 합니다.