Netwerkvereisten

Voor het gebruik van de RealityConnect API is uitgaande HTTPS-toegang tot de hieronder vermelde hosts vereist. Deze pagina behandelt het volledige netwerkpad: wat bereikbaar moet zijn, hoe proxy’s en TLS-inspectie verbindingen beïnvloeden, en hoe u een netwerkprobleem onderscheidt van een authenticatieprobleem.

Samenvatting van de vereisten

Alleen uitgaand, via HTTPS (poort 443). Er zijn geen inkomende poorten, firewallregels of NAT nodig. Zie Inkomende toegang.
Sta uitgaande HTTPS toe naar de onderstaande hostnamen.
Een standaard forward proxy van een bedrijf werkt transparant, ook een die authenticatie vereist. Zie Forward proxy’s.
Een TLS-inspecterende proxy verbreekt verbindingen, tenzij het rootcertificaat ervan wordt vertrouwd door de runtime van de integratie. Zie TLS-inspecterende proxy’s.

Inkomende toegang

Er hoeft niets inkomend te worden opengezet om de RealityConnect API te gebruiken. Uw integratie initieert de verbinding altijd uitgaand naar Prevu3D; Prevu3D opent nooit een verbinding terug naar uw netwerk. Er is geen webhook, callback-URL of listener om te registreren, en geen inkomende firewallregel om aan te maken.

Uitgaande toegang

Uw integratie moet drie soorten hosts kunnen bereiken via uitgaande HTTPS:

OAuth en API-discovery: https://cloud-api.prevu3d.com
Uw regionale RealityConnect API-host (precies één van):
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
Bestandsoverdrachten: https://cdn.prevu3d.com (downloads) en Amazon S3, *.amazonaws.com (vooraf ondertekende upload-URLs)

Welke regio is de mijne?

Uw organisatie is in precies één regio ingericht, dus u hoeft niet alle vier de hostnamen toe te staan. In plaats van te gokken of de support te vragen, laat u uw integratie het discovery-endpoint aanroepen (GET /oauth/api-info, beschreven in elke OAuth-flowgids) zodra u een token heeft: het veld apiUrl in de respons geeft aan welke regionale host uw organisatie daadwerkelijk gebruikt. Sta alleen die ene hostnaam toe; de andere drie kunt u overslaan.

Forward proxy’s

De RealityConnect API is een standaard HTTPS/JSON-API. Er wordt niets ongewoons van het netwerkpad vereist, en er wordt niets gedaan (zoals certificate pinning) dat werking via een standaard forward proxy van een bedrijf zou verhinderen.

Of uw integratie uw proxy daadwerkelijk gebruikt, hangt af van de HTTP-clientbibliotheek waarop deze is gebouwd, niet van de RealityConnect API:

De meeste HTTP-clients (curl, Python requests, Node undici/fetch, .NET HttpClient, enz.) respecteren de standaard omgevingsvariabelen HTTPS_PROXY / HTTP_PROXY, of een gelijkwaardige proxy-instelling in de clientconfiguratie. Raadpleeg de documentatie van uw clientbibliotheek om dit te bevestigen.
Geauthenticeerde proxy’s (die een gebruikersnaam en wachtwoord vereisen) worden eveneens op het niveau van de HTTP-client afgehandeld, via hetzelfde mechanisme voor proxy-inloggegevens dat de client al ondersteunt voor elke andere HTTPS-bestemming. De RealityConnect API stelt hier geen bijzondere eisen. Als uw client al andere HTTPS-diensten kan bereiken via uw geauthenticeerde proxy, kan deze de RealityConnect API op dezelfde manier bereiken.

TLS-inspecterende proxy’s

Sommige bedrijfsnetwerken gebruiken een TLS-inspecterende (SSL-decrypterende) proxy: deze bevindt zich in het midden van de verbinding, presenteert uw integratie zijn eigen certificaat in plaats van dat van Prevu3D, en versleutelt het verkeer opnieuw naar de werkelijke bestemming. Dit is een bekende oorzaak van verbindingsproblemen bij API-integraties in het algemeen, inclusief de RealityConnect API.

Hoe dit zich uit: in plaats van een normale respons mislukt de HTTPS-aanroep van uw integratie tijdens de TLS-handshake met een certificaatvalidatiefout. De exacte bewoording hangt af van uw HTTP-client en besturingssysteem, maar lijkt vaak op “unable to verify the first certificate”, “certificate verify failed”, “unknown certificate authority”, of een algemene verbindingsreset zonder enige HTTP-statuscode (omdat het verzoek nooit ver genoeg kwam om een respons te ontvangen).

Wat dit betekent: de runtime van uw integratie herkent het certificaat dat de inspecterende proxy presenteert niet, omdat deze de interne certificeringsinstantie (CA) niet vertrouwt die die proxy gebruikt om het verkeer opnieuw te ondertekenen.

Vereiste oplossing, een van beide opties:

Voeg de root-CA van het bedrijf toe aan de trust store die de integratie daadwerkelijk gebruikt. Dit is de meest voorkomende oplossing en de vaakst over het hoofd geziene stap: veel runtimes (Java, Node, Python) leveren of laden hun eigen CA-bundel in plaats van die van het besturingssysteem te gebruiken. Het installeren van de root-CA van het bedrijf in het Windows-certificaatarchief dekt deze niet automatisch. Controleer of uw taal/runtime een eigen configuratie nodig heeft (bijvoorbeeld een omgevingsvariabele NODE_EXTRA_CA_CERTS, een JVM-vlag -Djavax.net.ssl.trustStore, of het toevoegen van het certificaat aan de bundel die uw Python-installatie van requests/certifi gebruikt).
Sluit de hostnamen van de RealityConnect API uit van TLS-inspectie, als uw proxy regels voor uitzondering per bestemming ondersteunt. Dit is vaak eenvoudiger dan de trust store van elke afzonderlijke runtime te corrigeren.

Welke optie de juiste is, hangt af van de proxyleverancier en de runtime van de integratie.

Diagnose: ligt het aan het netwerk of aan de authenticatie?

Doorloop deze vier controles in volgorde. Elke controle isoleert een andere laag, zodat u ontdekt waar het probleem daadwerkelijk zit in plaats van authenticatiecode te debuggen voor een netwerkprobleem (of omgekeerd).

1. DNS

Bevestig dat de hostnaam wordt omgezet:

nslookup api-ue1.prevu3d.com

(Vervang dit door cloud-api.prevu3d.com of de regionale host van uw organisatie, naargelang van toepassing.) Als dit mislukt of time-out geeft, ligt het probleem bij de DNS-resolutie. Controleer de DNS-configuratie van de machine voordat u verdergaat.

2. TLS-handshake

Bevestig dat er een beveiligde verbinding met de host tot stand kan worden gebracht, onafhankelijk van een Prevu3D-specifiek verzoek:

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

Let op SSL certificate problem, unable to get local issuer certificate, of een verbinding die wordt gereset voordat er een HTTP-respons is. Dit alles wijst op een proxy- of firewallprobleem op het netwerkpad (zie TLS-inspecterende proxy’s hierboven), niet op iets in uw integratiecode. Een respons met een HTTP-statuscode, zelfs een foutcode zoals 401, betekent dat TLS is geslaagd en dat het probleem zich hoger in de stack bevindt.

De curl die met Windows wordt meegeleverd, gebruikt het Windows-certificaatarchief. Deze controle kan dus slagen terwijl een runtime met een eigen CA-bundel (Node, Python, Java) achter een TLS-inspecterende proxy nog steeds faalt. Slaagt de controle maar meldt uw integratie een certificaatfout, zie dan TLS-inspecterende proxy’s.

3. Token-aanvraag

Bevestig dat u een OAuth-toegangstoken kunt verkrijgen. Dit controleert of uw inloggegevens en uw OAuth-verzoek correct zijn opgebouwd, onafhankelijk van enige aanroep van de RealityConnect API:

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

Een 403 (onjuist secret) of 404 (onbekende client-ID) op dit punt is een probleem met de inloggegevens, geen netwerkprobleem, want DNS en TLS zijn al geslaagd om hier te komen.

4. Eerste geauthenticeerde aanroep

Bevestig dat het token daadwerkelijk werkt tegen de API:

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

Een geslaagde JSON-respons bevestigt hier dat het volledige pad (DNS, TLS en authenticatie) end-to-end werkt. Een 401/403 op dit punt, nadat stap 3 is geslaagd, wijst op een probleem met scopes of rechten in plaats van een netwerk- of inloggegevensprobleem. (/oauth/api-info vereist de scope read:basic.)

Wat is de volgende stap?

Aan de slag: vereisten, het beveiligingsmodel en het kiezen van een OAuth-flow.