Skapa en API-proxy för en GeoCatalog med Hjälp av Azure API Management

Den här artikeln beskriver hur du konfigurerar Azure API Management (APIM) som en API-proxy framför en Microsoft Planetary Computer Pro GeoCatalog. Med den här konfigurationen kan du:

  • Aktivera anonym åtkomst: anropare behöver inte sina egna Microsoft Entra-autentiseringsuppgifter. APIM autentiserar till GeoCatalog för deras räkning med hjälp av en hanterad identitet.
  • Icke-Entra-autentisering: anropare kan stödja icke-Entra-baserade autentiseringsmetoder. APIM autentiserar till GeoCatalog för deras räkning med hjälp av en hanterad identitet.
  • Framtvinga åtkomstkontroll på samlingsnivå: begränsa vilka StAC-samlingar (Spatiotemporal Access Catalog) som visas via proxyn, även om GeoCatalogs inte har inbyggt stöd för rollbaserad åtkomstkontroll på samlingsnivå (RBAC).

Följande diagram illustrerar arkitekturen före och efter att du har lagt till APIM-proxyn:

Innan Varje anropare autentiserar direkt till GeoCatalog:

caller ──(Entra token)──► GeoCatalog

Efter APIM finns mellan anropare och GeoCatalog, som hanterar autentisering och åtkomstkontroll:

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

Förutsättningar

Tilldela den hanterade identiteten till APIM

Innan APIM kan autentisera till din GeoCatalog måste du associera den användartilldelade hanterade identiteten med APIM-instansen.

  1. I Azure-portalen går du till din API Management-instans.
  2. Välj Identitet i det vänstra sidofältet.
  3. Välj fliken Användartilldelade .
  4. Välj Lägg till och välj sedan den användartilldelade hanterade identiteten som har rollen GeoCatalog-läsare i din GeoCatalog.
  5. Välj Lägg till för att bekräfta.

Skapa API:et i APIM

Definiera ett nytt API i APIM som proxyar förfrågningar till din GeoCatalog-backend.

  1. I din APIM-instans väljer du API:er i det vänstra sidofältet.

  2. Välj + Lägg till API>HTTP.

  3. Konfigurera API:et med följande inställningar:

    Inställning Value
    Visningsnamn Ett beskrivande namn (till exempel GeoCatalog API)
    Url för webbtjänst Din GeoCatalog-slutpunkt (till exempel https://<name>.<id>.<region>.geocatalog.spatio.azure.com)
    URL-schema HTTPS
    API URL-suffix Lämna tom (rotmappens sökväg)
    Prenumeration krävs Nej, för anonym åtkomst; Ja, för prenumerationsnyckelbaserad åtkomst

  4. Välj Skapa.

Definiera API-åtgärder

Lägg till följande åtgärder för att matcha GeoCatalog API-ytan. Jokerteckenåtgärderna (/*) vidarebefordrar alla matchande begäranden till serverdelen. Med de explicita insamlingsåtgärderna kan du tillämpa samlingsspecifika principer senare för åtkomstkontroll.

Visningsnamn Metod Mall för URL
GET GET /*
Hämta samlingsobjekt GET /stac/collections/{collection_id}/items
Hämta enskild samling GET /stac/collections/{collection_id}
Hämta samlingsunderresurser GET /stac/collections/{collection_id}/*
POST POST /*

Så här lägger du till varje åtgärd:

  1. Välj det API som du skapade.
  2. Välj + Lägg till åtgärd.
  3. Ange Visningsnamn, Metod och URL-mall från föregående tabell.
  4. Välj Spara.

Konfigurera principen på API-nivå

Principen på API-nivå hanterar autentisering och URL-omskrivning för hela API:et. Den här principen hämtar en token från den användartilldelade hanterade identiteten och kopplar den till varje begäran som vidarebefordras till GeoCatalog-serverdelen.

  1. Välj det API som du skapade och välj sedan Alla åtgärder.
  2. I avsnittet Inkommande bearbetning väljer du <ikonen /> (kodredigeraren).
  3. Ersätt principinnehållet med följande princip:
<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>

Ersätt följande platshållare:

Platshållare Value
<managed-identity-client-id> Klient-ID för den användartilldelade hanterade identiteten som tilldelats APIM
<name>.<id>.<region> Dina GeoCatalog-slutpunktskomponenter
<apim-name> Namnet på din APIM-instans

I följande tabell beskrivs varje principelement:

Principelement Avsikt
authentication-managed-identity Hämtar en token för målgruppen https://geocatalog.spatio.azure.com med den angivna hanterade identiteten och fäster den till den utgående förfrågan.
set-header (ta bort Accept-Encoding) Tar bort rubriken från inkommande begäranden. Se Varför ta bort Accept-Encoding.
find-and-replace Skriver om URL:en för GeoCatalog-serverdelen i svarstexter till APIM-gatewayens URL. Utan den här omskrivningen exponerar STAC-länkar (self, root, parentoch så vidare) serverdels-URL:en för anropare.

Varför ta bort Accept-Encoding

Klienter gillar Python requests och httpx skickar Accept-Encoding: gzip, deflate som standard. När backend tar emot denna header returneras ett komprimerat svar. APIM-principer för utgående trafik som find-and-replace fungerar på råsvarstexten och kan inte dekomprimera den, så de gör ingenting tyst. Om du tar bort rubriken tvingar du backend att returnera ett okomprimerat svar som utgående policys kan bearbeta.

Note

curl och wget skickar inte Accept-Encoding som standard. Det innebär att utgående principer verkar fungera korrekt när du testar med dessa verktyg. Inkonsekvensen visas bara med klienter som begär komprimering.

Framtvinga åtkomstkontroll på samlingsnivå

Som standard exponerar en GeoCatalog alla sina samlingar för alla autentiserade anropare. Om du vill begränsa vilka samlingar som visas via APIM använder du principer på åtgärdsnivå som blockerar bred STAC-identifiering och framtvingar en lista över tillåtna.

Definiera de tillåtna samlingarna

Skapa ett namngivet värde i APIM för att lagra listan över tillåtna samlings-ID:n:

  1. I DIN APIM-instans väljer du Namngivna värden i det vänstra sidofältet.
  2. Välj + Lägg till.
  3. Ange Namnet till allowed-collections.
  4. Ange värdet till en kommaavgränsad lista över tillåtna samlings-ID:t (till exempel sentinel-2-l2a,landsat-8-c2-l2).
  5. Välj Spara.

Blockera landningssidan och samlingslistan

Blockera de rutter som avslöjar varje samling i katalogen. Lägg till följande åtgärder och bifoga en princip som returnerar 404 omedelbart:

Visningsnamn Metod Mall för URL
Blockera root GET /
Blockera samlingar GET /stac/collections

Tillämpa följande princip på åtgärdsnivå för båda åtgärderna:

<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>

STAC-slutpunkten /stac/search accepterar en collections parameter – som en frågesträng på GET eller i JSON-brödtexten i POST. Utan begränsningar kan en användare söka i varje samling i katalogen. Följande policyer verifierar att endast samlingar från den tillåtna uppsättningen begärs.

Lägg till två åtgärder:

Visningsnamn Metod Mall för URL
GET-sökning GET /stac/search
POST-sökning POST /stac/search

GET /stac/search-policy

Den här principen validerar frågeparametern collections . Varje kommaavgränsat värde måste finnas i den tillåtna uppsättningen. Begäranden utan parameter collections avvisas med 403 Forbidden.

Tillämpa följande princip på GET-sökåtgärden :

<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-principuttryck körs i en begränsad C#-miljö. Använd condition='@{...}' (enskilt citattecken-attribut) så att dubbla citattecken kan användas i uttrycket. Undvik generiska typparametrar (till exempel GetValueOrDefault<string>) och LINQ lambdas – använd explicita casts och foreach loopar i stället.

Policy för POST /stac/search

Den här principen parsar JSON-brödtexten och validerar matrisen collections . Begäranden utan parameter collections avvisas med 403 Forbidden.

Tillämpa följande princip på POST-sökåtgärden :

<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>

Framtvinga tillåtna samlingar på samlingsslutpunkter

Utan explicita operationer, förfrågningar som GET /stac/collections/sentinel-2-l2a eller GET /stac/collections/sentinel-2-l2a/items faller genom till GET /* jokertecknet och når backend utan någon kontroll på insamlingsnivå. Tillämpa principen för path-parametrar som validerar collection_id mot {{allowed-collections}} på följande operationer du skapade i Definiera API-åtgärder:

Visningsnamn Metod Mall för URL
Hämta enskild samling GET /stac/collections/{collection_id}
Hämta samlingsunderresurser GET /stac/collections/{collection_id}/*
Hämta samlingsobjekt GET /stac/collections/{collection_id}/items

Tillämpa följande princip på alla tre åtgärderna:

<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>

Framtvinga tillåtna samlingar på SAS-tokenvägar

Med GEOCatalog SAS-API:et kan anropare generera lagringstoken och signera HREF:er för tillgångar. Utan begränsningar kan en anropare hämta token för alla samlingar. Följande principer säkerställer att endast tillåtna samlingar kan nås.

Lägg till följande åtgärder:

Visningsnamn Metod Mall för URL
HÄMTA SAS-token GET /sas/token/{collection_id}
Blockera SAS-tecken GET /sas/sign

Tillämpa blockeringsprincipen 404 (samma som rot- och samlingsblocket) på åtgärden Blockera SAS-tecken . Anropare bör använda /sas/token/{collection_id} för att hämta SAS-token på samlingsnivå i stället.

Tillämpa följande princip på åtgärden GET SAS-token :

<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>

Framtvinga tillåtna samlingar på datavägar

Slutpunkterna /data/mosaic/ tillhandahåller panelrendering, avgränsningsgrödor och sökregistrering. Det behövs två principgrupper:

  1. Registrera sökning – verifiera matrisen collections i JSON-brödtexten.
  2. Alla andra samlingsvägar – verifiera sökvägsparametern collectionId .

Lägg till följande åtgärder:

Visningsnamn Metod Mall för URL
POST-registersökning POST /data/mosaic/register
GET-datainsamling GET /data/mosaic/collections/{collectionId}/*

POST /data/mosaic/register policy

Den här principen validerar matrisen collections i JSON-objektet mot den tillåtna uppsättningen. Begäranden utan parameter collections avvisas.

<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

Den här principen validerar sökvägsparametern collectionId mot den tillåtna uppsättningen. Tillämpa den här principen på båda GET-datainsamlingsoperationerna.

<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>

Vanliga frågor och svar

Hur uppdaterar jag listan över tillåtna samlingar?

Redigera det namngivna allowed-collections värdet i APIM-instansen. Inga principändringar krävs.

Vad händer om en anropare utelämnar samlingsparametern?

Begäran avvisas med 403 Forbidden. Anropare måste alltid ange vilka samlingar de vill söka i.

Relaterat innehåll

  • Uppdaterades senast