Erstellen eines API-Proxys für einen GeoCatalog mit Azure API Management

Dieser Artikel führt Sie durch das Einrichten von Azure API Management (APIM) als API-Proxy vor einem Microsoft Planetary Computer Pro GeoCatalog. Mit dieser Konfiguration können Sie:

  • Anonymen Zugriff aktivieren: Anrufer benötigen keine eigenen Microsoft Entra-Anmeldeinformationen. APIM authentifiziert sich im Auftrag von GeoCatalog mithilfe einer verwalteten Identität.
  • Nicht-Entra-Authentifizierung: Aufrufer können nicht Entra-basierte Authentifizierungsmethoden unterstützen. APIM authentifiziert sich bei GeoCatalog in ihrem Auftrag mithilfe einer verwalteten Identität.
  • Erzwingen der Zugriffssteuerung auf Sammlungsebene: Einschränken, welche StaC-Auflistungen (Spatiotemporal Access Catalog) über den Proxy sichtbar sind, obwohl GeoCatalogs die rollenbasierte Zugriffssteuerung auf Sammlungsebene (RBAC) nicht nativ unterstützen.

Das folgende Diagramm veranschaulicht die Architektur vor und nach dem Hinzufügen des APIM-Proxys:

Bevor Jeder Aufrufer authentifiziert sich direkt beim GeoCatalog:

caller ──(Entra token)──► GeoCatalog

Nachdem sich APIM zwischen Benutzern und dem GeoCatalog befindet, behandelt es die Authentifizierung und Zugriffssteuerung.

caller ──(anonymous / APIM Subscription Keys)──► APIM ──(managed identity token)──► GeoCatalog

Voraussetzungen

Zuweisen der verwalteten Identität zu APIM

Bevor APIM sich bei Ihrem GeoCatalog authentifizieren kann, müssen Sie die vom Benutzer zugewiesene verwaltete Identität der APIM-Instanz zuordnen.

  1. Navigieren Sie im Azure-Portal zu Ihrer API-Verwaltungsinstanz.
  2. Wählen Sie "Identität" in der linken Randleiste aus.
  3. Wählen Sie die Registerkarte Benutzer zugewiesen aus.
  4. Wählen Sie "Hinzufügen" und dann die vom Benutzer zugewiesene verwaltete Identität aus, die die Rolle " GeoCatalog Reader" in Ihrem GeoCatalog enthält.
  5. Klicken Sie zur Bestätigung auf Hinzufügen.

Erstellen der API in APIM

Definieren Sie eine neue API in APIM, die Anfragen an Ihr GeoCatalog-Back-End weiterleitet.

  1. Wählen Sie in Ihrer APIM-Instanz APIs aus der linken Randleiste aus.

  2. Wählen Sie + API hinzufügen>HTTP.

  3. Konfigurieren Sie die API mit den folgenden Einstellungen:

    Setting Wert
    Anzeigename Ein beschreibender Name (z. B GeoCatalog API. )
    Webdienst-URL Ihr GeoCatalog-Endpunkt (z. B https://<name>.<id>.<region>.geocatalog.spatio.azure.com. )
    URL-Schema HTTPS
    API-URL-Suffix Leer lassen (Stammpfad)
    Abonnement erforderlich Nein, für anonymen Zugriff; Ja, für abonnementschlüsselbasierten Zugriff

  4. Wählen Sie "Erstellen" aus.

Definieren von API-Vorgängen

Fügen Sie die folgenden Vorgänge hinzu, um der GeoCatalog-API-Oberfläche zu entsprechen. Die Wildcardvorgänge (/*) leiten alle übereinstimmenden Anforderungen an das Back-End weiter. Mit den expliziten Sammlungsvorgängen können Sie sammlungsspezifische Richtlinien später für die Zugriffssteuerung anwenden.

Anzeigename Methode URL-Vorlage
GET GET /*
Elemente einer Sammlung abrufen GET /stac/collections/{collection_id}/items
Einzelne Sammlung abrufen GET /stac/collections/{collection_id}
Abrufen von Sammlungsunterressourcen GET /stac/collections/{collection_id}/*
POST POST /*

So fügen Sie jeden Vorgang hinzu:

  1. Wählen Sie die von Ihnen erstellte API aus.
  2. Wählen Sie + Vorgang hinzufügen.
  3. Geben Sie den Anzeigenamen, die Methode und die URL-Vorlage aus der vorherigen Tabelle ein.
  4. Wählen Sie "Speichern" aus.

Konfigurieren Sie die Richtlinie auf API-Ebene

Die Richtlinie auf API-Ebene handhabt die Authentifizierung und URL-Umschreibung für die gesamte API. Diese Richtlinie erwirbt ein Token aus der vom Benutzer zugewiesenen verwalteten Identität und fügt es an jede Anforderung an, die an das GeoCatalog-Back-End weitergeleitet wird.

  1. Wählen Sie die von Ihnen erstellte API und dann "Alle Vorgänge" aus.
  2. Wählen Sie im Abschnitt Eingehende Verarbeitung das </>-Symbol (Code-Editor) aus.
  3. Ersetzen Sie den Richtlinieninhalt durch die folgende Richtlinie:
<policies>
    <inbound>
        <base />
        <authentication-managed-identity
            resource="https://geocatalog.spatio.azure.com"
            client-id="<managed-identity-client-id>" />
        <set-header name="Accept-Encoding"
            exists-action="delete" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <find-and-replace
            from="https://<name>.<id>.<region>.geocatalog.spatio.azure.com"
            to="https://<apim-name>.azure-api.net" />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Ersetzen Sie die folgenden Platzhalter:

Placeholder Wert
<managed-identity-client-id> Die Client-ID der vom Benutzer zugewiesenen verwalteten Identität, die APIM zugewiesen ist
<name>.<id>.<region> Ihre GeoCatalog-Endpunktkomponenten
<apim-name> Der Name Ihrer APIM-Instanz

In der folgenden Tabelle werden die einzelnen Richtlinienelemente beschrieben:

Richtlinien-Element Purpose
authentication-managed-identity Erwirbt ein Token für die https://geocatalog.spatio.azure.com Zielgruppe mithilfe der angegebenen verwalteten Identität und fügt es an die ausgehende Anforderung an.
set-header (löschen Accept-Encoding) Entfernt den Accept-Encoding Header aus eingehenden Anforderungen. Siehe Warum Accept-Encoding entfernen.
find-and-replace Schreibt die URL des GeoCatalog-Backends in den Antworttexten in die URL des APIM-Gateways um. Ohne diese Neuschreibung machen STAC-Links (self, root, parentusw.) die Back-End-URL für Aufrufer verfügbar.

Warum Accept-Encoding entfernen?

Clients wie Python requests und httpx senden Accept-Encoding: gzip, deflate standardmäßig. Wenn das Back-End diesen Header empfängt, wird eine komprimierte Antwort zurückgegeben. APIM-Ausgangsrichtlinien wie find-and-replace wirken auf den rohen Antworttext und können ihn nicht dekomprimieren, sodass sie stillschweigend nichts tun. Durch das Entfernen des Headers wird das Back-End gezwungen, eine nicht komprimierte Antwort zurückzugeben, die von den Policies für ausgehenden Datenverkehr verarbeitet werden kann.

Note

curl und wget senden Accept-Encoding nicht standardmäßig. Dies bedeutet, dass ausgehende Richtlinien beim Testen mit diesen Tools korrekt funktionieren. Die Inkonsistenz tritt nur bei Clients auf, die Komprimierung anfordern.

Erzwingen der Zugriffssteuerung auf Sammlungsebene

Standardmäßig macht ein GeoCatalog alle zugehörigen Sammlungen für jeden authentifizierten Aufrufer verfügbar. Um einzuschränken, welche Sammlungen über APIM sichtbar sind, wenden Sie Richtlinien auf Vorgangsebene an, die die allgemeine STAC-Ermittlung blockieren und eine Zulassungsliste erzwingen.

Definieren Sie die zulässigen Sammlungen

Erstellen Sie einen benannten Wert in APIM, um die Liste der zulässigen Sammlungs-IDs zu speichern:

  1. Wählen Sie in Ihrer APIM-Instanz benannte Werte aus der linken Randleiste aus.
  2. Klicken Sie auf + Hinzufügen.
  3. Legen Sie den Namen auf allowed-collections.
  4. Legen Sie den Wert auf eine durch Kommas getrennte Liste zulässiger Auflistungs-IDs fest (z. B. sentinel-2-l2a,landsat-8-c2-l2).
  5. Wählen Sie "Speichern" aus.

Blockieren Sie die Landing-Seite und die Sammlungsliste.

Blockieren Sie die Routen, die jede Sammlung im Katalog anzeigen. Fügen Sie die folgenden Vorgänge hinzu, und fügen Sie eine Policy an, die sofort 404 zurückgibt:

Anzeigename Methode URL-Vorlage
Block Root GET /
Blocksammlungen GET /stac/collections

Wenden Sie die folgende Richtlinie auf Vorgangsebene auf beide Vorgänge an:

<policies>
    <inbound>
        <base />
        <return-response>
            <set-status code="404" reason="Not Found" />
        </return-response>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Der STAC-Endpunkt /stac/search akzeptiert einen collections Parameter – als Abfragezeichenfolge auf GET oder im JSON-Textkörper auf POST. Ohne Sicherheitsvorkehrungen könnte ein Benutzer in allen Sammlungen des Katalogs suchen. Die folgenden Policies überprüfen, ob nur Sammlungen aus dem zulässigen Satz angefordert werden.

Fügen Sie zwei Vorgänge hinzu:

Anzeigename Methode URL-Vorlage
GET-Suche GET /stac/search
POST-Suche POST /stac/search

GET /stac/Such-Policy

Diese Richtlinie überprüft den collections Abfrageparameter. Jeder durch Trennzeichen getrennte Wert muss im zulässigen Satz enthalten sein. Anforderungen ohne den Parameter collections werden mit 403 Forbidden abgelehnt.

Wenden Sie die folgende Richtlinie auf den GET-Suchvorgang an:

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var raw = context.Request.Url.Query
                    .GetValueOrDefault("collections", "");
                if (string.IsNullOrWhiteSpace(raw)) {
                    return true;
                }
                foreach (var c in raw.ToLower().Split(
                    new [] { "," },
                    StringSplitOptions.RemoveEmptyEntries))
                {
                    if (!c.Trim().Equals(allowed)) {
                        return true;
                    }
                }
                return false;
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Note

APIM-Richtlinienausdrücke werden in einer eingeschränkten C#-Umgebung ausgeführt. Verwenden Sie ein condition='@{...}' (einzelnes in Anführungszeichen gesetztes Attribut), sodass doppelte Anführungszeichen innerhalb des Ausdrucks funktionieren. Vermeiden Sie generische Typparameter (z. B. GetValueOrDefault<string>) und LINQ-Lambdas – verwenden Sie stattdessen explizite Umwandlungen und foreach Schleifen.

POST /stac/search policy

Diese Richtlinie analysiert den JSON-Textkörper und überprüft das collections Array. Anforderungen ohne Parameter collections werden mit 403 Forbidden abgelehnt.

Wenden Sie die folgende Richtlinie auf den POST-Suchvorgang an:

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <set-variable name="requestBody"
            value="@(context.Request.Body
                .As&lt;string&gt;(
                    preserveContent: true))" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var body = (string)context
                    .Variables["requestBody"];
                var json = Newtonsoft.Json.Linq
                    .JObject.Parse(body);
                var arr = json["collections"]
                    as Newtonsoft.Json.Linq.JArray;
                if (arr == null || arr.Count == 0) {
                    return true;
                }
                foreach (var token in arr) {
                    if (!token.ToString().Trim()
                        .ToLower().Equals(allowed))
                    {
                        return true;
                    }
                }
                return false;
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Erzwingen zulässiger Sammlungen auf Sammlungsendpunkten

Ohne explizite Vorgänge fallen Anforderungen wie GET /stac/collections/sentinel-2-l2a oder GET /stac/collections/sentinel-2-l2a/items auf die GET /*-Wildcard und erreichen das Back-End ohne Prüfung auf Sammlungsebene. Wenden Sie die Pfadparameterrichtlinie an, die collection_id anhand {{allowed-collections}} validiert, auf die folgenden Vorgänge, die Sie unter API-Vorgänge Definieren erstellt haben:

Anzeigename Methode URL-Vorlage
Abrufen einer einzelnen Sammlung GET /stac/collections/{collection_id}
Unterressourcen der Sammlung abrufen GET /stac/collections/{collection_id}/*
Sammlungselemente abrufen GET /stac/collections/{collection_id}/items

Wenden Sie die folgende Richtlinie auf alle drei Vorgänge an:

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var collectionId = (string)context
                    .Request.MatchedParameters[
                        "collection_id"];
                return !collectionId.Trim()
                    .ToLower().Equals(allowed);
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Durchsetzung zulässiger Sammlungen auf SAS-Token-Routen

Mit der GEOCatalog SAS-API können Aufrufer Speichertoken generieren und HREFs für Ressourcen signieren. Ohne Einschränkungen könnte ein Aufrufer Token für jede Sammlung abrufen. Die folgenden Richtlinien stellen sicher, dass nur auf zulässige Sammlungen zugegriffen werden kann.

Fügen Sie die folgenden Vorgänge hinzu:

Anzeigename Methode URL-Vorlage
GET SAS-Token GET /sas/token/{collection_id}
SAS-Zeichen blockieren GET /sas/sign

Wenden Sie die 404 Blockierungspolicy (identisch mit dem Root- und Sammlungsblock) auf den Vorgang SAS-Zeichen blockieren an. Aufrufer sollten /sas/token/{collection_id} stattdessen SAS-Token auf Sammlungsebene abrufen.

Wenden Sie die folgende Richtlinie auf den GET SAS-Tokenvorgang an:

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var collectionId = (string)context
                    .Request.MatchedParameters[
                        "collection_id"];
                return !collectionId.Trim()
                    .ToLower().Equals(allowed);
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Durchsetzen zulässiger Sammlungen auf Datenrouten

Die /data/mosaic/-Endpunkte stellen Kachelrendering, Ausschnitte anhand von Begrenzungsrahmen und Suchregistrierung bereit. Es sind zwei Richtliniengruppen erforderlich:

  1. Registersuche – überprüfen Sie das collections Array im JSON-Körper.
  2. Alle anderen Sammlungsrouten – überprüfen Sie den collectionId Pfadparameter.

Fügen Sie die folgenden Vorgänge hinzu:

Anzeigename Methode URL-Vorlage
POST-Registersuche POST /data/mosaic/register
GET-Datensammlung GET /data/mosaic/collections/{collectionId}/*

POST /data/mosaic/Registrierungs-Policy

Diese Policy überprüft das collections Array im JSON-Textkörper anhand des zulässigen Satzes. Anforderungen ohne Parameter collections werden abgelehnt.

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <set-variable name="requestBody"
            value="@(context.Request.Body
                .As&lt;string&gt;(
                    preserveContent: true))" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var body = (string)context
                    .Variables["requestBody"];
                var json = Newtonsoft.Json.Linq
                    .JObject.Parse(body);
                var arr = json["collections"]
                    as Newtonsoft.Json.Linq.JArray;
                if (arr == null || arr.Count == 0) {
                    return true;
                }
                foreach (var token in arr) {
                    if (!token.ToString().Trim()
                        .ToLower().Equals(allowed))
                    {
                        return true;
                    }
                }
                return false;
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

GET /data/mosaic/collections/{collectionId}/* Policy

Diese Policy überprüft den collectionId Pfadparameter für den zulässigen Satz. Wenden Sie diese Richtlinie auf die GET-Datensammlungsvorgänge an.

<policies>
    <inbound>
        <base />
        <set-variable name="allowedCsv"
            value="{{allowed-collections}}" />
        <choose>
            <when condition='@{
                var allowed = ((string)context
                    .Variables["allowedCsv"])
                    .Trim().ToLower();
                var collectionId = (string)context
                    .Request.MatchedParameters[
                        "collectionId"];
                return !collectionId.Trim()
                    .ToLower().Equals(allowed);
            }'>
                <return-response>
                    <set-status code="403"
                        reason="Forbidden" />
                    <set-body>
                        Collection not allowed.
                    </set-body>
                </return-response>
            </when>
        </choose>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Häufig gestellte Fragen

Wie aktualisiere ich die Liste der zulässigen Sammlungen?

Bearbeiten Sie den allowed-collections benannten Wert in der APIM-Instanz. Es sind keine Richtlinienänderungen erforderlich.

Was geschieht, wenn ein Aufrufer den Auflistungsparameter weglässt?

Die Anforderung wird mit 403 Forbidden abgelehnt. Anrufer müssen immer angeben, welche Sammlungen sie durchsuchen möchten.

Verwandte Inhalte

  • Last updated on