네트워크 요구 사항

RealityConnect API를 사용하려면 아래에 나열된 호스트에 대한 아웃바운드 HTTPS 액세스가 필요합니다. 이 페이지는 네트워크 경로 전체(도달 가능해야 하는 대상, 프록시와 TLS 검사가 연결에 미치는 영향, 네트워크 문제와 인증 문제를 구분하는 방법)를 다룹니다.

요구 사항 요약

아웃바운드만 필요하며, HTTPS(포트 443)를 사용합니다. 인바운드 포트, 방화벽 규칙, NAT는 전혀 필요하지 않습니다. 인바운드 접근을 참고하세요.
아래 호스트 이름으로의 아웃바운드 HTTPS를 허용하세요.
표준 기업 포워드 프록시는 인증이 필요한 경우를 포함해 투명하게 동작합니다. 포워드 프록시를 참고하세요.
TLS 검사 프록시는 연결을 끊습니다. 통합 환경의 런타임이 해당 루트 인증서를 신뢰하지 않는 경우 그렇습니다. TLS 검사 프록시를 참고하세요.

인바운드 접근

RealityConnect API를 사용하기 위해 인바운드로 열어야 하는 것은 없습니다. 통합은 항상 Prevu3D를 향해 아웃바운드로 연결을 시작하며, Prevu3D가 고객사 네트워크로 연결을 되돌려 여는 일은 없습니다. 등록해야 할 웹훅, 콜백 URL, 리스너가 없으며, 생성해야 할 인바운드 방화벽 규칙도 없습니다.

아웃바운드 접근

통합은 아웃바운드 HTTPS를 통해 세 종류의 호스트에 도달할 수 있어야 합니다.

OAuth 및 API 디스커버리: https://cloud-api.prevu3d.com
조직의 리전별 RealityConnect API 호스트(다음 중 정확히 하나):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
파일 전송: https://cdn.prevu3d.com (다운로드) 및 Amazon S3, *.amazonaws.com (사전 서명된 업로드 URL)

내 리전은 무엇인가

조직은 정확히 하나의 리전에 프로비저닝되므로, 네 개의 호스트 이름을 모두 허용할 필요는 없습니다. 추측하거나 지원팀에 문의하는 대신, 토큰을 확보한 후 통합이 디스커버리 엔드포인트(GET /oauth/api-info, 각 OAuth 플로 가이드에서 설명)를 호출하도록 하세요. 응답의 apiUrl 필드가 조직이 실제로 사용하는 리전 호스트를 알려줍니다. 그 호스트 이름 하나만 허용하면 되고, 나머지 세 개는 건너뛸 수 있습니다.

포워드 프록시

RealityConnect API는 표준 HTTPS/JSON API입니다. 네트워크 경로에 특별한 요구 사항이 없으며, 인증서 피닝과 같이 표준 기업 포워드 프록시를 통한 동작을 방해할 만한 어떠한 조치도 취하지 않습니다.

통합이 실제로 프록시를 사용하는지 여부는 RealityConnect API가 아니라 통합이 기반으로 하는 HTTP 클라이언트 라이브러리에 달려 있습니다.

대부분의 HTTP 클라이언트(curl, Python requests, Node의 undici/fetch, .NET의 HttpClient 등)는 표준 HTTPS_PROXY / HTTP_PROXY 환경 변수, 또는 클라이언트 설정 내 동등한 프록시 설정을 존중합니다. 이를 확인하려면 사용 중인 클라이언트 라이브러리의 문서를 참고하세요.
인증이 필요한 프록시(사용자 이름과 비밀번호를 요구하는 프록시)도 HTTP 클라이언트 계층에서 처리되며, 클라이언트가 이미 다른 모든 HTTPS 대상에 대해 지원하는 것과 동일한 프록시 자격 증명 메커니즘을 사용합니다. RealityConnect API 쪽에는 특별한 요구 사항이 없습니다. 클라이언트가 인증된 프록시를 통해 이미 다른 HTTPS 서비스에 접근할 수 있다면, 동일한 방식으로 RealityConnect API에도 접근할 수 있습니다.

TLS 검사 프록시

일부 기업 네트워크는 TLS 검사(SSL 복호화) 프록시를 운영합니다. 이 프록시는 연결 중간에 위치하여 Prevu3D의 인증서 대신 자체 인증서를 통합에 제시한 뒤, 실제 대상으로 향하는 트래픽을 다시 암호화합니다. 이는 일반적으로 API 통합에서 연결 문제를 일으키는 잘 알려진 원인이며, RealityConnect API도 예외가 아닙니다.

어떻게 나타나는가: 정상적인 응답 대신, 통합의 HTTPS 호출이 TLS 핸드셰이크 도중 인증서 검증 오류로 실패합니다. 정확한 문구는 사용 중인 HTTP 클라이언트와 운영체제에 따라 다르지만, 흔히 “unable to verify the first certificate”, “certificate verify failed”, “unknown certificate authority”와 같은 메시지로 나타나거나, HTTP 상태 코드조차 없는 일반적인 연결 재설정(요청이 응답을 받을 만큼 충분히 진행되지 못했기 때문)으로 나타나기도 합니다.

이것이 의미하는 바: 통합의 런타임이 검사 프록시가 제시한 인증서를 인식하지 못하는 것은, 해당 프록시가 트래픽을 재서명할 때 사용하는 내부 인증 기관(CA)을 런타임이 신뢰하지 않기 때문입니다.

필요한 조치, 다음 두 가지 중 하나:

통합이 실제로 사용하는 트러스트 스토어에 기업의 루트 CA를 추가합니다. 이는 가장 흔한 해결책이면서 가장 자주 놓치는 단계이기도 합니다. 많은 런타임(Java, Node, Python)이 운영체제의 것을 사용하는 대신 자체 CA 번들을 포함하거나 로드하므로, Windows 인증서 저장소에 기업의 루트 CA를 설치해도 이러한 런타임까지 자동으로 커버되지는 않습니다. 사용 중인 언어/런타임에 자체 설정이 필요한지 확인하세요(예: 환경 변수 NODE_EXTRA_CA_CERTS, JVM 플래그 -Djavax.net.ssl.trustStore, 또는 Python requests/certifi 설치가 사용하는 번들에 인증서를 추가하는 방법 등).
프록시가 대상별 우회 규칙을 지원한다면, RealityConnect API 호스트 이름을 TLS 검사 대상에서 제외합니다. 이는 런타임마다 개별적으로 트러스트 스토어를 수정하는 것보다 간단한 경우가 많습니다.

어떤 옵션이 적합한지는 프록시 공급업체와 통합의 런타임에 따라 달라집니다.

진단: 네트워크 문제인가, 인증 문제인가

다음 네 가지 확인을 순서대로 진행하세요. 각 단계는 서로 다른 계층을 분리하므로, 네트워크 문제에 대해 인증 코드를 디버깅하거나(혹은 그 반대의 경우) 하는 대신 실제 문제가 어디에 있는지 파악할 수 있습니다.

1. DNS

호스트 이름이 정상적으로 확인되는지 확인합니다.

nslookup api-ue1.prevu3d.com

(필요에 따라 cloud-api.prevu3d.com 또는 조직의 리전 호스트로 바꾸세요.) 이 단계가 실패하거나 시간 초과되면 문제는 DNS 확인에 있는 것입니다. 다음 단계로 넘어가기 전에 해당 머신의 DNS 설정을 확인하세요.

2. TLS 핸드셰이크

Prevu3D에 특정된 요청과 무관하게, 해당 호스트와 보안 연결을 수립할 수 있는지 확인합니다.

curl -v https://cloud-api.prevu3d.com

SSL certificate problem, unable to get local issuer certificate, 또는 HTTP 응답을 받기도 전에 연결이 재설정되는 현상을 확인하세요. 이는 모두 통합 코드의 문제가 아니라 네트워크 경로상의 프록시 또는 방화벽 문제를 나타냅니다(위의 TLS 검사 프록시 참고). 401와 같은 오류라도 HTTP 상태 코드가 포함된 응답을 받았다면 TLS는 성공한 것이며, 문제는 그보다 상위 계층에 있는 것입니다.

Windows에 기본 포함된 curl은 Windows 인증서 저장소를 사용하므로, 자체 CA 번들을 사용하는 런타임(Node, Python, Java)이 TLS 검사 프록시 뒤에서 여전히 실패하더라도 이 확인은 통과할 수 있습니다. 확인은 통과했지만 통합에서 인증서 오류가 발생한다면 TLS 검사 프록시을 참조하세요.

3. 토큰 요청

OAuth 액세스 토큰을 받을 수 있는지 확인합니다. 이는 RealityConnect API 호출과 무관하게, 자격 증명과 OAuth 요청이 올바르게 구성되어 있는지를 확인하는 단계입니다.

curl -v -X POST https://cloud-api.prevu3d.com/oauth/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=client_credentials"

이 단계에서 403 (잘못된 시크릿)이나 404 (알 수 없는 클라이언트 ID)가 반환된다면 이는 네트워크 문제가 아니라 자격 증명 문제입니다. 여기까지 도달했다는 것은 DNS와 TLS는 이미 성공했다는 뜻입니다.

4. 첫 번째 인증된 호출

토큰이 실제로 API에 대해 동작하는지 확인합니다.

curl -H "Authorization: Bearer <access_token>" https://cloud-api.prevu3d.com/oauth/api-info

여기서 성공적인 JSON 응답을 받으면 DNS, TLS, 인증을 포함한 전체 경로가 엔드투엔드로 정상 작동함을 확인한 것입니다. 3단계가 성공한 이후 이 단계에서 401/403이 반환된다면, 이는 네트워크나 자격 증명 문제가 아니라 스코프 또는 권한 문제를 나타냅니다. (/oauth/api-info에는 read:basic 스코프가 필요합니다.)

다음은?

시작하기: 전제 조건, 보안 모델, OAuth 플로 선택에 대해 설명합니다.