Condividi tramite

Autenticare e autorizzare l'accesso alle API OpenAI di Azure usando Gestione API di Azure

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Questo articolo illustra come autenticare e autorizzare gli endpoint API OpenAI di Azure gestiti tramite Gestione API di Azure. Questo articolo illustra i metodi comuni seguenti:

  • Autenticazione: eseguire l'autenticazione a un'API OpenAI di Azure usando criteri che eseguono l'autenticazione usando una chiave API o un'identità gestita di Microsoft Entra ID.

  • Autorizzazione: per un controllo di accesso più granulare, preautorizzare le richieste che passano token OAuth 2.0 generati da un provider di identità, ad esempio Microsoft Entra ID.

Per informazioni generali, vedere:

Prerequisiti

Prima di seguire i passaggi descritti in questo articolo, è necessario disporre di:

  • Un'istanza di Gestione API. Per i passaggi di esempio, vedere Creare un'istanza di Gestione API di Azure.
  • Una risorsa e un modello OpenAI di Azure aggiunti all'istanza di Gestione API. Per i passaggi di esempio, vedere Importare un'API OpenAI di Azure come API REST.
  • Autorizzazioni per creare una registrazione dell'app in un provider di identità, ad esempio un tenant di Microsoft Entra associato alla sottoscrizione di Azure (per l'autorizzazione OAuth 2.0).

Eseguire l'autenticazione con la chiave API

Un modo predefinito per eseguire l'autenticazione in un'API OpenAI di Azure consiste nell'usare una chiave API. Per questo tipo di autenticazione, tutte le richieste API devono includere una chiave API valida nell'intestazione HTTP api-key.

  • Gestione API può gestire la chiave API in modo sicuro usando un valore denominato.
  • È quindi possibile fare riferimento al valore denominato in un criterio API per impostare l'intestazione api-key nelle richieste all'API OpenAI di Azure. Vengono forniti due esempi di come eseguire questa operazione: uno usa il criterio set-backend-service e l'altro usa il criterio set-header.

Archiviare la chiave API in un valore denominato

  1. Ottenere una chiave API dalla risorsa OpenAI di Azure. Nel portale di Azure trovare una chiave nella pagina Chiavi ed endpoint della risorsa OpenAI di Azure.
  2. Passare all'istanza di Gestione API e selezionare Valori denominati nel menu a sinistra.
  3. Selezionare + Aggiungi e aggiungere il valore come segreto o, facoltativamente, per maggiore sicurezza, usare un riferimento all'insieme di credenziali delle chiavi.

Passare la chiave API nelle richieste API - set-backend-service policy

  1. Creare un back-end che punti all'API OpenAI di Azure.

    1. Nel menu a sinistra dell'istanza di Gestione API selezionare Back-end.
    2. Selezionare + Aggiungi e immettere un nome descrittivo per il back-end. Esempio: openai-backend.
    3. In Tipo, selezionare Personalizzato e immettere l'URL dell'endpoint OpenAI di Azure. Esempio: https://contoso.openai.azure.com/openai.
    4. In credenziali di autorizzazione, selezionare intestazioni e immettere chiave API come nome dell'intestazione e il valore denominato come valore.
    5. Seleziona Crea.

  2. Aggiungere il frammento di criterio set-backend-service seguente nella sezione criteri inbound per passare la chiave API nelle richieste all'API OpenAI di Azure.

    In questo esempio la risorsa back-end è openai-backend.

    <set-backend-service backend-id="openai-backend" />

Passare la chiave API nelle richieste API - criterio set-header

In alternativa, aggiungere il frammento di criterio set-header seguente nella sezione criteri inbound per passare la chiave API nelle richieste all'API OpenAI di Azure. Questo frammento di codice di criteri imposta l'intestazione api-key con il valore denominato configurato.

In questo esempio, il valore denominato in Gestione API è openai-api-key.

<set-header name="api-key" exists-action="override">
    <value>{{openai-api-key}}</value>
</set-header>

Eseguire l'autenticazione con un'identità gestita

Un modo alternativo per eseguire l'autenticazione a un'API OpenAI di Azure usando un'identità gestita in Microsoft Entra ID. Per informazioni generali, vedere Come configurare il servizio Azure OpenAI con identità gestita.

Di seguito sono riportati i passaggi per configurare l'istanza di Gestione API in modo da usare un'identità gestita per autenticare le richieste a un'API OpenAI di Azure.

  1. Abilitare un'identità gestita assegnata dal sistema o assegnata dall'utente per l'istanza di Gestione API. L'esempio seguente presuppone che sia stata abilitata l'identità gestita assegnata dal sistema dell'istanza.

  2. Assegnare l'identità gestita al ruolo utente OpenAI di Servizi cognitivi, con ambito alla risorsa appropriata. Ad esempio, assegnare all'identità gestita assegnata dal sistema il ruolo utente OpenAI di Servizi cognitivi nella risorsa OpenAI di Azure. Per i passaggi dettagliati, vedere Controllo degli accessi in base al ruolo per il servizio Azure OpenAI.

  3. Aggiungere il frammento di criterio seguente nella sezione criteri inbound per autenticare le richieste all'API OpenAI di Azure usando l'identità gestita.

    In questo esempio:

    <authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" /> 
<set-header name="Authorization" exists-action="override"> 
    <value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value> 
</set-header>

Autorizzazione OAuth 2.0 con il provider di identità

Per abilitare l'accesso più dettagliato alle API OpenAPI da utenti o client specifici, è possibile preautorizzare l'accesso all'API OpenAI di Azure usando l'autorizzazione OAuth 2.0 con l'ID Microsoft Entra o un altro provider di identità. Per informazioni generali, vedere Proteggere un'API in Gestione API di Azure usando l'autorizzazione OAuth 2.0 con Microsoft Entra ID.

Nota

Usare l'autorizzazione OAuth 2.0 come parte di una strategia di difesa avanzata. Non è una sostituzione per l'autenticazione della chiave API o l'autenticazione dell'identità gestita a un'API OpenAI di Azure.

Di seguito sono riportati i passaggi generali per limitare l'accesso API agli utenti o alle app autorizzate tramite un provider di identità.

  1. Creare un'applicazione nel provider di identità per rappresentare l'API OpenAI in Gestione API di Azure. Se si usa Microsoft Entra ID, registrare un'applicazione nel tenant microsoft Entra ID. Registrare i dettagli, ad esempio l'ID applicazione e l'URI del gruppo di destinatari.

    Se necessario, configurare l'applicazione in modo che disponga di ruoli o ambiti che rappresentano le autorizzazioni con granularità fine necessarie per accedere all'API OpenAI di Azure.

  2. Aggiungere un frammento di criteri inbound nell'istanza di Gestione API per convalidare le richieste che presentano un token Web JSON (JWT) nell'intestazione Authorization. Inserire questo frammento di codice prima di altri criteri inbound impostati per l'autenticazione all'API OpenAI di Azure.

    Nota

    Gli esempi seguenti illustrano la struttura generale dei criteri per convalidare un token JWT. Personalizzarli in base al provider di identità e ai requisiti dell'applicazione e dell'API.

    • validate-azure-ad-token: se si usa Microsoft Entra ID, configurare i criteri validate-azure-ad-token per convalidare il gruppo di destinatari e le attestazioni nel token JWT. Per informazioni dettagliate, vedere le informazioni di riferimento sui criteri.

      <validate-azure-ad-token tenant-id={{TENANT_ID}} header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <client-application-ids>
            <application-id>{{CLIENT_APP_ID}}</application-id>
    </client-application-ids>
   <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

    • validate-jwt: se si usa un altro provider di identità, configurare i criteri validate-jwt per convalidare il gruppo di destinatari e le attestazioni nel token JWT. Per informazioni dettagliate, vedere le informazioni di riferimento sui criteri.

      <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url={{OPENID_CONFIGURATION_URL}} />
    <issuers>
        <issuer>{{ISSUER_URL}}</issuer>
    </issuers>
    <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-jwt>

Contenuto correlato