Exigences réseau

L’utilisation de la RealityConnect API nécessite un accès HTTPS sortant vers les hôtes listés ci-dessous. Cette page couvre l’ensemble du chemin réseau : ce qui doit être joignable, l’effet des proxys et de l’inspection TLS sur les connexions, et comment distinguer un problème réseau d’un problème d’authentification.

Résumé des exigences

Sortant uniquement, en HTTPS (port 443). Aucun port entrant, règle de pare-feu ou NAT n’est nécessaire. Voir Accès entrant.
Autorisez le HTTPS sortant vers les noms d’hôte ci-dessous.
Un proxy sortant (forward proxy) d’entreprise standard fonctionne de manière transparente, y compris s’il nécessite une authentification. Voir Proxys sortants.
Un proxy d’inspection TLS interrompra les connexions, sauf si son certificat racine est approuvé par l’environnement d’exécution de l’intégration. Voir Proxys d’inspection TLS.

Accès entrant

Rien ne doit être ouvert en entrée pour utiliser la RealityConnect API. Votre intégration établit toujours la connexion en sortant vers Prevu3D ; Prevu3D n’ouvre jamais de connexion entrante vers votre réseau. Il n’y a aucun webhook, aucune URL de callback ni aucun listener à enregistrer, et aucune règle de pare-feu entrante à créer.

Accès sortant

Votre intégration doit pouvoir joindre trois types d’hôtes en HTTPS sortant :

OAuth et découverte de l’API : https://cloud-api.prevu3d.com
Votre hôte régional de la RealityConnect API (exactement un parmi) :
- https://api-ue1.prevu3d.com
- https://api-ec1.prevu3d.com
- https://api-an1.prevu3d.com
- https://api-cc1.prevu3d.com
Transferts de fichiers: https://cdn.prevu3d.com (téléchargements) et Amazon S3, *.amazonaws.com (URLs de téléversement présignées)

Quelle est ma région ?

Votre organisation est provisionnée dans une seule région, vous n’avez donc pas besoin d’autoriser les quatre noms d’hôte. Plutôt que de deviner ou de demander au support, faites appeler par votre intégration le point de terminaison de découverte (GET /oauth/api-info, décrit dans chaque guide de flux OAuth) une fois que vous disposez d’un token : le champ apiUrl de la réponse indique quel hôte régional votre organisation utilise réellement. Autorisez ce seul nom d’hôte ; vous pouvez ignorer les trois autres.

Proxys sortants

La RealityConnect API est une API HTTPS/JSON standard. Elle n’exige rien d’inhabituel du chemin réseau, et ne fait rien (comme l’épinglage de certificat) qui empêcherait son fonctionnement via un proxy sortant d’entreprise standard.

Le fait que votre intégration utilise effectivement votre proxy dépend de la bibliothèque client HTTP sur laquelle elle est construite, pas de la RealityConnect API :

La plupart des clients HTTP (curl, requests en Python, undici/fetch de Node, HttpClient de .NET, etc.) respectent les variables d’environnement standard HTTPS_PROXY / HTTP_PROXY, ou un paramètre de proxy équivalent dans la configuration du client. Consultez la documentation de votre bibliothèque cliente pour le confirmer.
Les proxys authentifiés (nécessitant un nom d’utilisateur et un mot de passe) sont également gérés au niveau du client HTTP, via le même mécanisme d’identifiants de proxy que le client prend déjà en charge pour toute autre destination HTTPS. La RealityConnect API n’a aucune exigence particulière ici. Si votre client peut déjà atteindre d’autres services HTTPS via votre proxy authentifié, il peut atteindre la RealityConnect API de la même manière.

Proxys d’inspection TLS

Certains réseaux d’entreprise exploitent un proxy d’inspection TLS (déchiffrement SSL) : il s’intercale au milieu de la connexion, présente son propre certificat à votre intégration à la place de celui de Prevu3D, puis rechiffre le trafic vers la destination réelle. C’est une cause connue d’échecs de connexion pour les intégrations d’API en général, la RealityConnect API y compris.

Comment cela se manifeste : au lieu d’une réponse normale, l’appel HTTPS de votre intégration échoue pendant la négociation TLS (handshake) avec une erreur de validation de certificat. Le message exact dépend de votre client HTTP et de votre système d’exploitation, mais ressemble souvent à « unable to verify the first certificate », « certificate verify failed », « unknown certificate authority », ou une simple réinitialisation de connexion sans code de statut HTTP du tout (car la requête n’est jamais allée assez loin pour recevoir une réponse).

Ce que cela signifie : l’environnement d’exécution de votre intégration ne reconnaît pas le certificat présenté par le proxy d’inspection, car il ne fait pas confiance à l’autorité de certification (CA) interne que ce proxy utilise pour re-signer le trafic.

Correction requise, l’une des deux options suivantes :

Ajoutez l’autorité de certification racine de l’entreprise au magasin de confiance (trust store) réellement utilisé par l’intégration. C’est la solution la plus courante, et l’étape la plus souvent oubliée : de nombreux environnements d’exécution (Java, Node, Python) fournissent ou chargent leur propre ensemble de certificats CA au lieu d’utiliser celui du système d’exploitation. Installer l’autorité de certification racine de l’entreprise dans le magasin de certificats Windows ne les couvre pas automatiquement. Vérifiez si votre langage/environnement d’exécution nécessite sa propre configuration (par exemple une variable d’environnement NODE_EXTRA_CA_CERTS, une option JVM -Djavax.net.ssl.trustStore, ou l’ajout du certificat à l’ensemble utilisé par votre installation Python requests/certifi).
Excluez les noms d’hôte de la RealityConnect API de l’inspection TLS, si votre proxy prend en charge des règles de contournement par destination. C’est souvent plus simple que de corriger le magasin de confiance de chaque environnement d’exécution individuellement.

La bonne option dépend de l’éditeur du proxy et de l’environnement d’exécution de l’intégration.

Diagnostic : est-ce le réseau ou l’authentification ?

Effectuez ces quatre vérifications dans l’ordre. Chacune isole une couche différente, afin que vous trouviez où se situe réellement le problème plutôt que de déboguer du code d’authentification pour un problème réseau (ou l’inverse).

1. DNS

Vérifiez que le nom d’hôte se résout tout court :

nslookup api-ue1.prevu3d.com

(Remplacez par cloud-api.prevu3d.com ou l’hôte régional de votre organisation, selon le cas.) Si cela échoue ou expire, le problème vient de la résolution DNS. Vérifiez la configuration DNS de la machine avant d’aller plus loin.

2. Négociation TLS (handshake)

Vérifiez qu’une connexion sécurisée peut être établie avec l’hôte, indépendamment de toute requête spécifique à Prevu3D :

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

Recherchez SSL certificate problem, unable to get local issuer certificate, ou une connexion réinitialisée avant toute réponse HTTP. Tout cela indique un problème de proxy ou de pare-feu sur le chemin réseau (voir Proxys d’inspection TLS ci-dessus), pas un problème dans le code de votre intégration. Une réponse avec un code de statut HTTP, même une erreur comme 401, signifie que le TLS a réussi et que le problème se situe plus haut dans la pile.

Le curl fourni avec Windows utilise le magasin de certificats Windows : cette vérification peut donc réussir alors qu’un environnement d’exécution doté de son propre bundle de CA (Node, Python, Java) échoue toujours derrière un proxy d’inspection TLS. Si la vérification réussit mais que votre intégration signale une erreur de certificat, consultez Proxys d’inspection TLS.

3. Requête de token

Vérifiez que vous pouvez obtenir un token d’accès OAuth. Cela permet de vérifier que vos identifiants et votre requête OAuth sont correctement formés, indépendamment de tout appel à la RealityConnect API :

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

Un 403 (secret incorrect) ou 404 (client ID inconnu) à cette étape est un problème d’identifiants, pas un problème réseau, car le DNS et le TLS ont déjà réussi pour arriver jusque-là.

4. Premier appel authentifié

Vérifiez que le token fonctionne réellement avec l’API :

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

Une réponse JSON réussie confirme ici que l’ensemble du chemin (DNS, TLS et authentification) fonctionne de bout en bout. Un 401/403 à cette étape, après la réussite de l’étape 3, indique un problème de scopes ou de permissions plutôt qu’un problème réseau ou d’identifiants. (/oauth/api-info requiert le scope read:basic.)

Et ensuite ?

Premiers pas : prérequis, modèle de sécurité, et choix d’un flux OAuth.