Creare un proxy API per un GeoCatalog usando Gestione API di Azure

Questo articolo illustra come configurare API Management di Azure come proxy API davanti a un GeoCatalogo Computer Planetario Pro di Microsoft. Con questa configurazione è possibile:

• Abilitare l'accesso anonimo: i chiamanti non necessitano delle proprie credenziali di Microsoft Entra. APIM esegue l'autenticazione a GeoCatalog per loro conto usando un'identità gestita.
• Autenticazione non Entra: i chiamanti possono supportare metodi di autenticazione non basati su Entra. APIM esegue l'autenticazione a GeoCatalog per conto dell'utente usando un'identità gestita.
• Applicare il controllo di accesso a livello di raccolta: limitare le raccolte SPAtiotemporal Access Catalog (STAC) visibili tramite il proxy, anche se GeoCatalogs non supportano in modo nativo il controllo degli accessi in base al ruolo a livello di raccolta.

Il diagramma seguente illustra l'architettura prima e dopo l'aggiunta del proxy APIM.

Prima Ogni chiamante esegue l'autenticazione direttamente al GeoCatalog:

caller ──(Entra token)──► GeoCatalog

Dopo APIM si trova tra i chiamanti e il GeoCatalog, gestendo l'autenticazione e il controllo degli accessi.

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

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuito.
• Una risorsa GeoCatalog esistente.
• Istanza di Gestione API di Azure.
• Una identità gestita assegnata dall'utente all'istanza di Gestione API con un'assegnazione di ruolo Lettore GeoCatalog sulla risorsa GeoCatalog. Vedere Gestire l'accesso per le istruzioni per l'assegnazione di ruolo.

Assegnare l'identità gestita ad APIM

Prima che Gestione API possa eseguire l'autenticazione a GeoCatalog, è necessario associare l'identità gestita assegnata dall'utente all'istanza di Gestione API.

1. Nel portale di Azure accedere all'istanza di Gestione API.
2. Selezionare Identity (Identità ) nella barra laterale sinistra.
3. Selezionare la scheda Assegnato all'utente.
4. Selezionare Aggiungi, quindi scegliere l'identità gestita assegnata dall'utente con il ruolo di Lettore GeoCatalog assegnato al tuo GeoCatalogo.
5. Selezionare Aggiungi per confermare.

Creare l'API in APIM

Definire una nuova API in Gestione API che indirizza le richieste al back-end GeoCatalog.

1. Nell'istanza APIM selezionare API dalla barra laterale sinistra.

2. Selezionare + Aggiungi API>HTTP.

3. Configurare l'API con le impostazioni seguenti:

   Impostazione	Valore
   Nome visualizzato	Nome descrittivo (ad esempio, GeoCatalog API)
   URL del servizio Web	Il tuo endpoint GeoCatalog (ad esempio, https://<name>.<id>.<region>.geocatalog.spatio.azure.com)
   Schema URL	HTTPS
   Suffisso URL API	Lasciare vuoto (percorso radice)
   Sottoscrizione obbligatoria	No, per Accesso anonimo; Sì, per l'accesso basato su chiave di sottoscrizione

4. Fare clic su Crea.

Definire le operazioni API

Aggiungere le operazioni seguenti per corrispondere con la superficie dell'API GeoCatalog. Le operazioni con caratteri jolly (/*) inoltrano tutte le richieste corrispondenti al back-end. Le operazioni di raccolta esplicite consentono di applicare criteri specifici della raccolta in un secondo momento per il controllo di accesso.

Per aggiungere ogni operazione:

1. Selezionare l'API creata.
2. Selezionare + Aggiungi operazione.
3. Immettere il Nome visualizzato, Metodo e il modello URL dalla tabella precedente.
4. Seleziona Salva.

Configurare i criteri a livello di API

I criteri a livello di API gestiscono l'autenticazione e la riscrittura degli URL per l'intera API. Questo criterio acquisisce un token dall'identità gestita assegnata dall'utente e lo associa a ogni richiesta inoltrata al back-end GeoCatalog.

1. Selezionare l'API creata, quindi selezionare Tutte le operazioni.
2. Nella sezione Elaborazione in ingresso selezionare l'icona </> (editor di codice).
3. Sostituire il contenuto dei criteri con i criteri seguenti:

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

Sostituire i segnaposto seguenti:

La tabella seguente descrive ogni elemento dei criteri:

Perché rimuovere "Accept-Encoding"

Client come Python requests e httpx inviano Accept-Encoding: gzip, deflate per impostazione predefinita. Quando il back-end riceve questa intestazione, restituisce una risposta compressa. I criteri di uscita di Gestione API, come find-and-replace, operano sul corpo della risposta grezzo e non possono decomprimerlo, pertanto non eseguono alcuna azione. La rimozione dell'intestazione forza il back-end a restituire una risposta non compressa che i criteri in uscita possono elaborare.

Applicare il controllo di accesso a livello di raccolta

Per impostazione predefinita, un GeoCatalog espone tutte le raccolte a qualsiasi chiamante autenticato. Per limitare quali raccolte sono visibili tramite APIM, applicare criteri a livello di operazione che bloccano l'individuazione esaustiva di STAC e fanno rispettare un elenco di autorizzazioni.

Definire le raccolte consentite

Creare un valore con nome in APIM per archiviare l'elenco degli ID raccolta consentiti.

1. Nell'istanza di APIM, seleziona Valori denominati dalla barra laterale sinistra.
2. Seleziona + Aggiungi.
3. Impostare Nome su allowed-collections.
4. Impostare Value su un elenco di ID raccolta consentiti delimitato da virgole, ad esempio sentinel-2-l2a,landsat-8-c2-l2.
5. Seleziona Salva.

Bloccare la pagina di destinazione e l'elenco di raccolte

Bloccare le route che rivelano qualsiasi raccolta nel catalogo. Aggiungere le operazioni seguenti e allegare un criterio che restituisce 404 immediatamente:

Applicare i criteri a livello di operazione seguenti a entrambe le operazioni:

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

Applicare le raccolte consentite nella ricerca STAC

L'endpoint STAC /stac/search accetta un collections parametro, come stringa di query in GET o nel corpo JSON in POST. Senza protezioni, un chiamante potrebbe eseguire ricerche in ogni raccolta nel catalogo. I criteri seguenti convalidano che vengano richieste solo le raccolte del set consentito.

Aggiungere due operazioni:

GET /stac/criteri ricerca

Questo criterio convalida il collections parametro di query. Ogni valore delimitato da virgole deve essere incluso nel set consentito. Le richieste senza un collections parametro vengono rifiutate con 403 Forbidden.

Applicare i criteri seguenti all'operazione di ricerca GET :

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

POST /stac/criteri ricerca

Questo criterio analizza il corpo JSON e convalida la collections matrice. Le richieste senza un collections parametro vengono rifiutate con 403 Forbidden.

Applicare i criteri seguenti all'operazione di ricerca POST :

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

Applicare le raccolte consentite agli endpoint di raccolta

Senza operazioni esplicite, le richieste come GET /stac/collections/sentinel-2-l2a o GET /stac/collections/sentinel-2-l2a/items passano al carattere jolly GET /* e raggiungono il back-end senza alcun controllo a livello di raccolta. Applicare il criterio path-parameter che valida collection_id rispetto a {{allowed-collections}} per le operazioni seguenti create in Definire le operazioni API:

Applicare i criteri seguenti a tutte e tre le operazioni:

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

Applicare le raccolte consentite nelle route del token SAS

L'API SAS di GeoCatalog consente agli utenti di generare token di archiviazione e firmare gli HREF degli asset. Senza restrizioni, un chiamante potrebbe ottenere token per qualsiasi raccolta. I criteri seguenti assicurano che sia possibile accedere solo alle raccolte consentite.

Aggiungere le operazioni seguenti:

Applicare il criterio di blocco 404 (uguale al blocco radice e raccolte) all'operazione Blocca segno SAS. I chiamanti devono usare /sas/token/{collection_id} per ottenere invece token di firma di accesso condiviso a livello di raccolta.

Applicare i criteri seguenti all'operazione 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>

Implementare le raccolte consentite sui percorsi dei dati

Gli endpoint /data/mosaic/ forniscono il rendering dei riquadri, i ritagli di rettangoli delimitatore e la registrazione della ricerca. Sono necessari due gruppi di criteri:

1. Ricerca del registro - convalidare l'collections array nel corpo JSON.
2. Tutte le altre route di raccolta: convalidare il parametro di percorso collectionId.

Aggiungere le operazioni seguenti:

POST /data/mosaic/criterio di registrazione

Questo criterio convalida la collections matrice nel corpo JSON rispetto al set consentito. Le richieste senza un collections parametro vengono rifiutate.

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

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

Questo criterio convalida il collectionId parametro path rispetto al set consentito. Applicare questo criterio a entrambe le operazioni di raccolta dati GET .

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

Domande frequenti

Come si aggiorna l'elenco delle raccolte consentite?

Modificare il valore con nome allowed-collections nell'istanza di APIM. Non sono necessarie modifiche ai criteri.

Cosa accade se un chiamante omette il parametro collections?

La richiesta viene rifiutata con 403 Forbidden. I chiamanti devono sempre specificare le raccolte da cercare.

Contenuti correlati

• Documentazione di Gestione API di Azure
• Informazioni di riferimento per i criteri di Gestione API
• Gestire l'accesso per Microsoft Planetary Computer Pro
• Configurare l'autenticazione dell'applicazione per Microsoft Planetary Computer Pro
• Assegnare un'identità gestita assegnata dall'utente a un GeoCatalog