Azure API Management を使用して Azure OpenAI API に対するアクセスの認証と認可を行う

  • [アーティクル]

適用対象: すべての API Management レベル

この記事では、Azure API Management を使用して管理されている Azure OpenAI API エンドポイントに対する認証と認可を行う方法について学習します。 この記事では、次の一般的な方法を示します。

  • 認証 - API キーまたは Microsoft Entra ID マネージド ID を使用して認証するポリシーを使用して Azure OpenAI API に対して認証を行います。

  • 認可 - アクセスの制御をより細かく行うために、Microsoft Entra ID などの ID プロバイダーによって生成された OAuth 2.0 トークンを渡す要求を事前認可します。

背景については、以下を参照してください。

前提条件

この記事のステップを実行するには、以下が必要です。

  • API Management インスタンス。 例のステップについては、Azure API Management インスタンスの作成に関する記事を参照してください。
  • API Management インスタンスに追加された Azure OpenAI リソースとモデル。 例のステップについては、「REST API として Azure OpenAI API をインポートする」を参照してください。
  • Azure サブスクリプションに (OAuth 2.0 認可のために) 関連付けられている Microsoft Entra テナントなどの ID プロバイダーでアプリ登録を作成するためのアクセス許可。

API キー で認証する

Azure OpenAI API に対する既定の認証方法は、API キーを使用することです。 この種類の認証の場合、すべての API 要求で、api-key HTTP ヘッダーに有効な API キーを含める必要があります。

  • API Management では、名前付きの値を使用して、安全な方法で API キーを管理できます。
  • その後、名前付きの値を API ポリシーで参照して、Azure OpenAI API への要求の api-key ヘッダーを設定できます。 この方法の 2 つの例を示します。1 つは set-backend-service ポリシーを使用し、もう 1 つは set-header ポリシーを使用します。

名前付きの値に API キーを格納する

  1. Azure OpenAI リソースから API キーを取得します。 Azure portal で、Azure OpenAI リソースの [キーとエンドポイント] ページでキーを見つけます。
  2. Azure API Management インスタンスに移動し、左側のメニューから [名前付きの値] を選択します。
  3. [+ 追加] を選択し、値をシークレットとして追加するか、必要に応じてキー コンテナー参照を使用してセキュリティを高めます。

API 要求で API キーを渡す - set-backend-service ポリシー

  1. Azure OpenAI API を指すバックエンドを作成します。

    1. API Management インスタンスの左側のメニューで [バックエンド] を選択します。
    2. [+ 追加] を選択し、バックエンドにわかりやすい名前を入力します。 例: openai-backend。
    3. [種類] で [カスタム] を選択し、Azure OpenAI エンドポイントの URL を入力します。 例: https://contoso.openai.azure.com/openai。
    4. [認可資格情報] で、[ヘッダー] を選択し、ヘッダー名として「api-key」と入力し、値として名前付きの値を入力します。
    5. ［作成］ を選択します

  2. inbound ポリシー セクションに次の set-backend-service ポリシー スニペットを追加して、要求の API キーを Azure OpenAI API に渡します。

    この例では、バックエンド リソースは openai-backend です。

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

API 要求で API キーを渡す - set-header ポリシー

または、inbound ポリシー セクションに次の set-header ポリシー スニペットを追加して、要求の API キーを Azure OpenAI API に渡します。 このポリシー スニペットは、設定した名前付きの値を api-key ヘッダーに設定します。

この例では、API Management の名前付きの値は openai-api-key です。

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

マネージド ID による認証

Microsoft Entra ID のマネージド ID を使用して Azure OpenAI API に対して認証する別の方法です。 背景については、「マネージド ID を使用して Azure OpenAI Service を構成する方法」を参照してください。

マネージド ID を使用して Azure OpenAI API への要求を認証するように API Management インスタンスを構成するステップを次に示します。

  1. API Management インスタンスで、システムによって割り当てられた、またはユーザーが割り当てたマネージド ID を有効にします。 次の例は、インスタンスのシステム割り当てマネージド ID が有効になっていることを前提としています。

  2. マネージド ID に、適切なリソースをスコープとして Cognitive Services OpenAI ユーザー ロールを割り当てます。 たとえば、システム割り当てマネージド ID に、Azure OpenAI リソースの Cognitive Services OpenAI ユーザー ロールを割り当てます。 詳細なステップについては、「Azure OpenAI Service のロールベースのアクセス制御」を参照してください。

  3. マネージド ID を使用して Azure OpenAI API に対する要求を認証するため、inbound ポリシー セクションに次のポリシー スニペットを追加します。

    次の点に注意してください。

    • authentication-managed-identity ポリシーは、マネージド ID のアクセス トークンを取得します。
    • set-header ポリシーは、アクセス トークンを使用して要求の Authorization ヘッダーを設定します。
    <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>

ID プロバイダーを使用した OAuth 2.0 認可

特定のユーザーまたはクライアントによる OpenAPI API へのよりきめ細かなアクセスを有効にするために、Microsoft Entra ID または別の ID プロバイダーで OAuth 2.0 認可を使用して Azure OpenAI API へのアクセスを事前認可できます。 背景については、「OAuth 2.0 認可と Microsoft Entra ID を使用して Azure API Management で API を保護する」を参照してください。

Note

多層防御戦略の一環として OAuth 2.0 認可を使用します。 これは、Azure OpenAI API に対する API キー認証またはマネージド ID 認証に代わるものではありません。

ID プロバイダーを使用して認可されたユーザーまたはアプリへの API アクセスを制限するステップの概要を次に示します。

  1. Azure API Management で OpenAI API を表すアプリケーションを ID プロバイダーに作成します。 Microsoft Entra ID を使用している場合は、Microsoft Entra ID テナントにアプリケーションを登録します。 アプリケーション ID や対象ユーザー URI などの詳細を記録してください。

    必要に応じて、Azure OpenAI API にアクセスするために必要なきめ細かいアクセス許可を表すロールまたはスコープを持つアプリケーションを構成します。

  2. API Management インスタンスに inbound ポリシー スニペットを追加して、Authorization ヘッダーに JSON Web トークン (JWT) を提示する要求を検証します。 Azure OpenAI API に対して認証するように設定した他のinbound ポリシーより "前に"、このスニペットを配置してください。

    Note

    次の例は、JWT を検証するためのポリシーの一般的な構造を示しています。 ID プロバイダーやアプリケーションと API の要件に合わせてカスタマイズしてください。

    • validate-azure-ad-token - Microsoft Entra ID を使用する場合は、JWT の対象ユーザーと要求を検証するように validate-azure-ad-token ポリシーを構成します。 詳細については、ポリシーのリファレンスを参照してください。

      <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 - 別の ID プロバイダーを使用する場合は、JWT の対象ユーザーと要求を検証するように validate-jwt ポリシーを構成します。 詳細については、ポリシーのリファレンスを参照してください。

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

関連するコンテンツ