CORS und der HMAC-Endpunkt

Wird eine WebGIS API Anwendung nicht im Portal selbst, sondern auf einer Drittseite (einem anderen Server) eingebunden, muss diese Seite in der portal.config freigegeben werden, sofern angemeldete Benutzer darauf zugreifen (siehe unten). Dieses Kapitel erklärt, warum das notwendig ist und wie es konfiguriert wird.

Hintergrund: Same-Origin-Policy und CORS

Ein Browser erlaubt es JavaScript-Code standardmäßig nur, Antworten von der eigenen Origin zu lesen. Eine Origin besteht aus Schema, Host und Port, z. B. https://example.com (https://example.com:8443 und http://example.com sind jeweils andere Origins). Das ist die sogenannte Same-Origin-Policy.

Soll eine Seite auf https://example.com trotzdem Antworten eines anderen Servers (z. B. https://webgisserver.com) lesen dürfen, muss der andere Server dies über CORS (Cross-Origin Resource Sharing) ausdrücklich erlauben. Dazu sendet der Server den HTTP-Header Access-Control-Allow-Origin mit der erlaubten Origin zurück. Fehlt dieser Header oder passt die Origin nicht, verwirft der Browser die Antwort und der Aufruf schlägt fehl.

Wozu dient der HMAC-Endpunkt?

Das Portal stellt den Endpunkt https://webgisserver.com/portal/hmac bereit. Über diesen werden Zugangsdaten (Keys) für den Zugriff auf die API für den aktuell angemeldeten Benutzer abgeholt. Eine WebGIS API Anwendung ruft diesen Endpunkt auf, um sich gegenüber der API als dieser Benutzer auszuweisen.

Das Problem: Der Browser sendet bei einem solchen Aufruf die Anmeldung des Benutzers am Portal (Cookie) automatisch mit. Ohne Schutz könnte daher jede beliebige Webseite im Hintergrund den hmac-Request aufrufen und die Keys für den Besucher der Seite abfragen:

  1. Ein angemeldeter Benutzer besucht eine Schadseite https://evil.example.

  2. Deren JavaScript ruft https://webgisserver.com/portal/hmac auf.

  3. Ohne CORS-Schutz könnte die Seite die Antwort lesen und hätte damit Zugriff auf die API im Namen des Benutzers.

Mit der CORS-Policy beantwortet das Portal den hmac-Request nur dann mit einem passenden Access-Control-Allow-Origin-Header, wenn die aufrufende Origin ausdrücklich freigegeben wurde. Für alle anderen Seiten verweigert der Browser das Lesen der Antwort.

Wann wird /hmac benötigt?

Der Aufruf von /hmac auf einer Drittseite ist nur dann notwendig, wenn angemeldete Benutzer auf eine API Anwendung zugreifen. Wie der Anwender auf der Drittseite zu einem Cookie (oder einer vergleichbaren Anmeldung am Portal) kommt, wird nicht über WebGIS geregelt.

Für anonyme Anwendungen ist es besser, eine Client ID zu vergeben:

  • Die Client ID bezieht sich immer auf einen HTTP-Referer, der beim API Client eingestellt werden kann (siehe API Client anlegen und verwalten).

  • Ist ein API Key bzw. eine Client ID vorhanden, wird /hmac in der Regel nicht aufgerufen. Der Anwender erbt automatisch die Rechte des Clients.

  • In diesem Fall ist für die Drittseite kein Eintrag in add-cors-origins-for-hmac notwendig.

Anwendungsfall

Empfohlene Vorgehensweise

Anonyme Anwendung auf Drittseite

API Client mit Client ID und HTTP-Referer; kein /hmac, kein CORS-Eintrag

Angemeldete Benutzer auf Drittseite

/hmac am Portal; Drittseite in add-cors-origins-for-hmac eintragen

Konfiguration

Die erlaubten Origins werden in der Datei _config/portal.config mit dem Schlüssel add-cors-origins-for-hmac als kommagetrennte Liste angegeben (Beschreibung des Schlüssels: Konfiguration der Portal Applikation, Abschnitt Advanced Security):

<add key="add-cors-origins-for-hmac" value="https://localhost,https://example.com" />

Regeln:

  • Es sind alle Server anzuführen, auf denen eine WebGIS API Anwendung eingebunden ist.

  • Jeder Eintrag besteht aus Schema, Host und ggf. Port, ohne Pfad und ohne abschließenden Schrägstrich (https://example.com bzw. https://example.com:8443).

  • Schema und Port müssen exakt stimmen: https://example.com erlaubt weder http://example.com noch https://www.example.com.

  • Einträge werden durch Komma getrennt, ohne Leerzeichen.

  • Seiten, die vom selben Server wie das Portal ausgeliefert werden (gleiche Origin), benötigen keinen Eintrag.

  • Nach einer Änderung der portal.config ist die Portal-Anwendung neu zu starten.

Beispiel

Das Portal läuft auf https://webgisserver.com/portal. Die Gemeinde betreibt eine eigene Webseite https://gemeinde.example.org/karte.html, in die eine WebGIS API Anwendung eingebunden ist. Zusätzlich wird lokal entwickelt (https://localhost). Die portal.config lautet dann:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <!-- ... weitere Einstellungen ... -->

    <!-- Erlaubte Origins (CORS) für den HMAC-Endpunkt -->
    <add key="add-cors-origins-for-hmac"
         value="https://gemeinde.example.org,https://localhost" />
  </appSettings>
</configuration>

Ergebnis:

Aufrufende Seite

Ergebnis

https://gemeinde.example.org/karte.html

erlaubt (Origin https://gemeinde.example.org ist eingetragen)

https://localhost

erlaubt

http://gemeinde.example.org

blockiert (anderes Schema)

https://www.gemeinde.example.org

blockiert (anderer Host)

https://evil.example

blockiert (nicht eingetragen)

Fehlersuche

Ist eine Origin nicht eingetragen, funktioniert die eingebundene Anwendung nicht wie erwartet (z. B. keine Anmeldung an der API). In den Entwicklertools des Browsers (F12, Konsole bzw. Netzwerk) erscheint dann eine Meldung ähnlich:

Access to fetch at 'https://webgisserver.com/portal/hmac' from origin
'https://gemeinde.example.org' has been blocked by CORS policy: No
'Access-Control-Allow-Origin' header is present on the requested resource.

In diesem Fall ist die in der Meldung genannte Origin (hier https://gemeinde.example.org) in add-cors-origins-for-hmac zu ergänzen.

Aufrufe an andere Portal-Seiten (Default-Policy)

Alle Portal-Seiten außer /hmac verwenden die Default-Policy. Erlaubt sind (mit Anmeldung) nur die Portal-Url, die API-Url und die in add-cors-origins-for-default angeführten Origins (gleiche Schreibweise und Regeln wie bei add-cors-origins-for-hmac). Aufrufe von anderen Origins werden vom Browser blockiert. Bisher wurde hier jede anfragende Origin erlaubt.

<add key="add-cors-origins-for-default" value="https://example.com" />

Sollen fremde Seiten Antworten des Portals lesen dürfen, jedoch ohne Anmeldung (Cookies), kann dies optional erlaubt werden:

<add key="cors-default-allow-any-origin-without-credentials" value="true" />

Für die Einbindung von WebGIS API Anwendungen auf Drittseiten ist normalerweise nur add-cors-origins-for-hmac notwendig.

Wildcard ~

Der Wert ~ ist ein Wildcard und erlaubt alle Seiten:

<add key="add-cors-origins-for-hmac" value="~" />

Der Wildcard gilt auch für add-cors-origins-for-default. Ist er gesetzt, schreibt das Portal beim Start eine Warnung ins Logfile.

Gefahr

Der Wildcard hebt den oben beschriebenen Schutz vollständig auf. Er sollte nur in Ausnahmefällen zum Testen verwendet werden und niemals in einer Produktionsumgebung.