Eigen domeinnaam koppelen aan het Pitane Link portaal

Wilt u het Pitane-portaal beschikbaar maken via uw eigen domeinnaam, bijvoorbeeld:

https://portaal.uwdomein.nl

terwijl het portaal op de achtergrond wordt geladen vanaf:

https://tp.pitanelink.eu/?apiKey=UW_API_KEY

Dan zijn er een aantal zaken waar u rekening mee moet houden. Hieronder beantwoorden we de meest voorkomende vragen.

Kan ik hiervoor alleen een CNAME-record gebruiken?

Nee. Een CNAME-record kan een subdomein, zoals portaal.uwdomein.nl, wel naar een andere hostnaam laten verwijzen, maar kan geen URL met een pad of parameters instellen.

Een CNAME kan bijvoorbeeld verwijzen naar:

tp.pitanelink.eu

maar niet naar:

https://tp.pitanelink.eu/?apiKey=UW_API_KEY

Daarnaast zorgt een CNAME er niet automatisch voor dat het SSL-certificaat en de webapplicatie geschikt zijn voor uw eigen domeinnaam.

Wat heb ik dan nodig?

Wanneer u wilt dat de gebruiker in de adresbalk uitsluitend uw eigen domeinnaam ziet, bijvoorbeeld:

https://portaal.uwdomein.nl

heeft u een reverse proxy nodig.

De situatie wordt dan:

Gebruiker → portaal.uwdomein.nl → uw reverse proxy → Pitane-portaal

De reverse proxy ontvangt het verzoek van de gebruiker en vraagt vervolgens op de achtergrond de betreffende pagina bij het Pitane-platform op.

Blijft mijn eigen domeinnaam dan in de adresbalk staan?

Ja. Dat is juist een belangrijk verschil tussen een redirect en een reverse proxy. Bij een gewone redirect wordt de gebruiker doorgestuurd en verandert de adresbalk bijvoorbeeld in: https://tp.pitanelink.eu/?apiKey=...

Bij een correct geconfigureerde reverse proxy kan de adresbalk op: https://portaal.uwdomein.nl blijven staan.

Waar stel ik de reverse proxy in?

Dat hangt af van uw eigen hostingomgeving. Een reverse proxy kan bijvoorbeeld worden ingericht op een webserver met Nginx of Apache, een eigen VPS/server, een hostingomgeving die reverse proxies ondersteunt of een daarvoor geschikte proxy-/cloudoplossing. Uw hosting- of systeembeheerder kan aangeven of uw huidige omgeving hiervoor geschikt is.

Wat moet ik in DNS instellen?

U moet ervoor zorgen dat:

portaal.uwdomein.nl

uitkomt bij de server of dienst waarop uw reverse proxy actief is.

Afhankelijk van uw omgeving kan hiervoor bijvoorbeeld een A-record of CNAME-record nodig zijn.

Let op: DNS verzorgt alleen het bereiken van de juiste server. De daadwerkelijke koppeling met het Pitane-portaal wordt daarna door de reverse proxy uitgevoerd.

Heb ik een SSL-certificaat nodig?

Ja.

https://portaal.uwdomein.nl

moet over een geldig SSL/TLS-certificaat beschikken. Dit certificaat moet specifiek geldig zijn voor portaal.uwdomein.nl.

Veel hostingomgevingen kunnen hiervoor automatisch een certificaat van bijvoorbeeld Let's Encrypt aanvragen. Controleer na de configuratie altijd of de browser geen certificaatwaarschuwing geeft.

Hoe wordt mijn API-key gebruikt?

De API-key is bedoeld om toegang te krijgen tot de juiste omgeving. De reverse proxy kan deze bij het verzoek naar het Pitane-platform meesturen.

Bijvoorbeeld:

https://tp.pitanelink.eu/?apiKey=UW_API_KEY

Idealiter wordt de API-key uitsluitend aan de serverzijde geconfigureerd en niet onnodig gepubliceerd in DNS-records, 

openbare configuratiebestanden of documentatie.

Behandel een API-key als vertrouwelijke informatie. Deel deze niet publiekelijk en plaats hem niet in voorbeelden, screenshots of openbare handleidingen.

Wanneer een API-key per ongeluk openbaar is gemaakt, adviseren wij deze te laten vervangen.

Kan ik niet gewoon een redirect instellen?

Dat kan wanneer het geen probleem is dat de gebruiker uiteindelijk tp.pitanelink.eu in zijn adresbalk ziet. Wilt u juist dat de gebruiker gedurende het gebruik van het portaal: portaal.uwdomein.nl blijft zien, dan is een redirect niet voldoende en is een reverse proxy de aangewezen oplossing.

Werkt een reverse proxy altijd direct?

Niet noodzakelijk.

Een moderne webapplicatie kan gebruikmaken van onder andere JavaScript, API-verzoeken, cookies, WebSockets, redirects en absolute URL's. Wanneer de applicatie bijvoorbeeld zelf verwijzingen naar https://tp.pitanelink.eu/... genereert, kan aanvullende configuratie noodzakelijk zijn.

Test daarom na het instellen minimaal:

• inloggen en uitloggen;

• navigeren tussen verschillende pagina's;

• formulieren verzenden;

• downloaden en uploaden van bestanden, indien van toepassing;

• openen van links;

• werking van cookies en sessies;

• gebruik op desktop en mobiel;

• eventuele realtimefunctionaliteit.

Waar moet mijn beheerder technisch op letten?

De reverse proxy moet HTTPS-verkeer correct afhandelen en verzoeken doorsturen naar tp.pitanelink.eu.

Daarnaast moet worden gecontroleerd of onder andere de Host-header, cookies, redirects, queryparameters, WebSockets en eventuele API-aanroepen correct via de proxy verlopen. Voorkom bovendien dat gebruikers via de proxy willekeurige waarden kunnen gebruiken om de ingestelde API-key te overschrijven.

Kan ik meerdere klanten of omgevingen op deze manier koppelen?

In principe kan per eigen domein of subdomein een afzonderlijke configuratie worden gemaakt, bijvoorbeeld:

portaal.bedrijf-a.nl
portaal.bedrijf-b.nl

Iedere omgeving kan vervolgens server-side aan de daarvoor bestemde configuratie en API-key worden gekoppeld.

Zorg ervoor dat API-keys strikt van elkaar gescheiden blijven.

Hoe controleer ik of alles correct is ingesteld?

Open na de configuratie:

https://portaal.uwdomein.nl

Controleer vervolgens of:

1. het juiste Pitane-portaal verschijnt;

2. portaal.uwdomein.nl in de adresbalk blijft staan;

3. HTTPS zonder certificaatwaarschuwing werkt;

4. inloggen, navigeren en uitloggen correct functioneren;

5. er geen onverwachte verwijzingen naar de oorspronkelijke URL ontstaan;

6. de API-key niet onnodig zichtbaar wordt voor gebruikers.

Test bij voorkeur ook in een privé-/incognitovenster zodat bestaande cookies en sessies de test niet beïnvloeden.

Wie is verantwoordelijk voor de configuratie?

De DNS-, SSL- en reverse-proxyconfiguratie voor uwdomein.nl wordt uitgevoerd binnen uw eigen hosting- of serveromgeving. Wanneer u deze omgeving niet zelf beheert, kunt u deze FAQ doorsturen naar uw hostingpartij of systeembeheerder. Geef daarbij aan dat u het Pitane-portaal via een reverse proxy onder een eigen HTTPS-subdomein beschikbaar wilt maken.

Samengevat

Wilt u alleen doorsturen naar Pitane en mag de Pitane-URL zichtbaar worden? Dan kan een redirect voldoende zijn.

Wilt u dat portaal.uwdomein.nl tijdens het gebruik zichtbaar blijft? Dan heeft u een reverse proxy nodig. Een CNAME alleen is hiervoor niet voldoende. Zorg daarnaast altijd voor een geldig SSL-certificaat, veilige opslag van de API-key en een volledige functionele test van het portaal.