Authentifizieren und Autorisieren des Zugriffs auf Azure OpenAI-APIs mithilfe von Azure API Management

  • Artikel

GILT FÜR: Alle API Management-Ebenen

In diesem Artikel erfahren Sie mehr über Methoden zum Authentifizieren und Autorisieren bei Azure OpenAI-API-Endpunkten, die mit Azure API Management verwaltet werden. In diesem Artikel werden die folgenden allgemeinen Methoden beschrieben:

  • Authentifizierung – Authentifizieren bei einer Azure OpenAI-API mithilfe von Richtlinien, die entweder mit einem API-Schlüssel oder einer verwalteten Identität von Microsoft Entra ID authentifizieren.

  • Autorisierung – Um eine differenziertere Zugriffssteuerung zu erhalten, autorisieren Sie vorab Anforderungen, die OAuth 2.0-Token übergeben, die von einem Identitätsanbieter wie Microsoft Entra ID generiert werden.

Hintergrundinformationen finden Sie unter:

Voraussetzungen

Bevor Sie die Schritte in diesem Artikel ausführen können, benötigen Sie Folgendes:

  • Eine API Management-Instanz. Beispielschritte finden Sie unter Erstellen einer Azure API Management-Instanz.
  • Eine Azure OpenAI-Ressource und ein Azure OpenAI-Modell, die Ihrer API Management-Instanz hinzugefügt wurden. Beispielschritte finden Sie unter Importieren einer Azure OpenAI-API als REST-API.
  • Berechtigungen zum Erstellen einer App-Registrierung in einem Identitätsanbieter, z. B. einem Microsoft Entra-Mandanten, der Ihrem Abonnement zugeordnet ist (für OAuth 2.0-Autorisierung).

Authentifizieren mit einem API-Schlüssel

Eine Standardmethode zum Authentifizieren bei einer Azure OpenAI-API ist die Verwendung eines API-Schlüssels. Bei dieser Art der Authentifizierung müssen alle API-Anforderungen den API-Schlüssel in den api-key-HTTP-Header einbeziehen.

  • API Management kann den API-Schlüssel auf sichere Weise verwalten, indem ein benannter Wert verwendet wird.
  • Auf den benannten Wert kann dann in einer API-Richtlinie verwiesen werden, um den api-key-Header in Anforderungen an die Azure OpenAI-API festzulegen. Wir stellen zwei Beispiele zur Vorgehensweise bereit: das eine verwendet die set-backend-service-Richtlinie und das andere verwendet die set-header-Richtlinie.

Speichern des API-Schlüssels in einem benannten Wert

  1. Rufen Sie einen API-Schlüssel aus der Azure OpenAI-Ressource ab. Suchen Sie im Azure-Portal einen Schlüssel auf der Seite Schlüssel und Endpunkt der Azure OpenAI-Ressource.
  2. Wechseln Sie zu Ihrer API Management-Instanz, und wählen Sie im Menü auf der linken Seite Benannte Werte aus.
  3. Wählen Sie + Hinzufügen aus, und fügen Sie den Wert als Geheimnis hinzu, oder verwenden Sie optional für mehr Sicherheit einen Schlüsseltresorverweis.

Übergeben des API-Schlüssels in API-Anforderungen – „Set-Backend-Service“-Richtlinie (Back-End-Dienst festlegen)

  1. Erstellen Sie ein Back-End, das auf die Azure OpenAI-API verweist.

    1. Wählen Sie im Menü auf der linken Seite Ihrer API Management-Instanz die Option Back-Ends aus.
    2. Wählen Sie + Hinzufügen aus, und geben Sie einen beschreibenden Namen für das Back-End ein. Beispiel: openai-backend.
    3. Wählen Sie unter Typ die Option Benutzerdefiniert aus, und geben Sie die URL des Azure OpenAI-Endpunkts ein. Beispiel: https://contoso.openai.azure.com/openai.
    4. Wählen Sie unter Autorisierungsanmeldeinformationen die Option Headeraus, und geben Sie api-key als Headernamen und den benannten Wert als Wert ein.
    5. Klicken Sie auf Erstellen.

  2. Fügen Sie den folgenden set-backend-service-Richtlinienausschnitt im inbound-Richtlinienabschnitt hinzu, um den API-Schlüssel in Anforderungen an die Azure OpenAI-API zu übergeben.

    In diesem Beispiel lautet die Back-End-Ressource openai-backend.

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

Übergeben des API-Schlüssels in API-Anforderungen – „Set-Header“-Richtlinie (Header festlegen)

Fügen Sie alternativ den folgenden set-header-Richtlinienausschnitt im inbound-Richtlinienabschnitt hinzu, um den API-Schlüssel in Anforderungen an die Azure OpenAI-API zu übergeben. Dieser Richtlinienausschnitt legt den api-key-Header mit dem benannten Wert fest, den Sie eingerichtet haben.

In diesem Beispiel lautet der benannte Wert in API Management openai-api-key.

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

Authentifizieren mit einer verwalteten Identität

Eine alternative Methode zum Authentifizieren bei einer Azure OpenAI-API mithilfe einer verwalteten Identität in Microsoft Entra ID. Hintergrundinformationen finden Sie unter Konfigurieren von Azure OpenAI Service mit verwalteten Identitäten.

Im Folgenden werden Schritte zum Konfigurieren Ihrer API Management-Instanz beschrieben, um eine verwaltete Identität zum Authentifizieren von Anforderungen an eine Azure OpenAI-API zu verwenden.

  1. Aktivieren Sie eine system- oder benutzerseitig zugewiesene verwaltete Identität für Ihre API Management-Instanz. Im folgenden Beispiel wird davon ausgegangen, dass Sie die systemseitig zugewiesene verwaltete Identität der Instanz aktiviert haben.

  2. Weisen Sie die verwaltete Identität der Rolle Cognitive Services OpenAI-Benutzer zu, die auf die entsprechende Ressource festgelegt ist. Weisen Sie beispielsweise die systemseitig zugewiesene verwaltete Identität der Rolle Cognitive Services OpenAI-Benutzer in der Azure OpenAI-Ressource zu. Ausführliche Schritte finden Sie unter Rollenbasierte Zugriffssteuerung für Azure OpenAI Service.

  3. Fügen Sie den folgenden Richtlinienausschnitt im inbound-Richtlinienabschnitt hinzu, um Anforderungen an die Azure OpenAI-API mithilfe der verwalteten Identität zu authentifizieren.

    In diesem Beispiel:

    • Die authentication-managed-identity-Richtlinie ruft ein Zugriffstoken für die verwaltete Identität ab.
    • Die set-header-Richtlinie legt den Authorization-Header der Anforderung mit dem Zugriffstoken fest.
    <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>

OAuth 2.0-Autorisierung mithilfe des Identitätsanbieters

Um einen differenzierteren Zugriff auf OpenAPI-APIs durch bestimmte Benutzer oder Clients zu ermöglichen, können Sie den Zugriff auf die Azure OpenAI-API mithilfe der OAuth 2.0-Autorisierung mit Microsoft Entra ID oder einem anderen Identitätsanbieter vorab authentifizieren. Hintergrundinformationen finden Sie unter Schützen einer API in Azure API Management mithilfe der OAuth 2.0-Autorisierung mit Microsoft Entra ID.

Hinweis

Verwenden Sie die OAuth 2.0-Autorisierung als Teil einer Defense-in-Depth-Strategie. Sie ist kein Ersatz für die API-Schlüsselauthentifizierung oder verwaltete Identitätsauthentifizierung für eine Azure OpenAI-API.

Im Folgenden werden allgemeine Schritte zum Einschränken des API-Zugriffs auf Benutzer oder Apps beschrieben, die mithilfe eines Identitätsanbieters autorisiert werden.

  1. Erstellen Sie eine Anwendung in Ihrem Identitätsanbieter, um die OpenAI-API in Azure API Management darzustellen. Wenn Sie Microsoft Entra ID verwenden, registrieren Sie eine Anwendung in Ihrem Microsoft Entra ID-Mandanten. Notieren Sie Details wie die Anwendungs-ID und den Zielgruppen-URI.

    Konfigurieren Sie die Anwendung nach Bedarf so, dass sie über Rollen oder Bereiche verfügt, die die differenzierten Berechtigungen darstellen, die für den Zugriff auf die Azure OpenAI-API erforderlich sind.

  2. Fügen Sie einen inbound-Richtlinienausschnitt in Ihrer API Management-Instanz hinzu, um Anforderungen zu überprüfen, die ein JSON-Webtoken (JWT) im Authorization-Header darstellen. Platzieren Sie diesen Ausschnitt vorinbound anderen -Richtlinien, die Sie für die Authentifizierung bei der Azure OpenAI-API festgelegt haben.

    Hinweis

    In den folgenden Beispielen wird die allgemeine Struktur der Richtlinien zum Überprüfen eines JWT gezeigt. Passen Sie sie an Ihren Identitätsanbieter und die Anforderungen Ihrer Anwendung und API an.

    • validate-azure-ad-token – Wenn Sie Microsoft Entra ID verwenden, konfigurieren Sie die validate-azure-ad-token-Richtlinie, um die Zielgruppe und Ansprüche im JWT zu überprüfen. Details finden Sie in der Richtlinienreferenz.

      <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 – Wenn Sie einen anderen Identitätsanbieter verwenden, konfigurieren Sie die validate-jwt-Richtlinie, um die Zielgruppe und Ansprüche im JWT zu überprüfen. Details finden Sie in der Richtlinienreferenz.

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

Zugehöriger Inhalt