Edit

Share via

Authenticate and authorize access to Azure OpenAI APIs using Azure API Management

  • Article

APPLIES TO: All API Management tiers

In this article, you learn about ways to authenticate and authorize to Azure OpenAI API endpoints that are managed using Azure API Management. This article shows the following common methods:

  • Authentication - Authenticate to an Azure OpenAI API using policies that authenticate using either an API key or a Microsoft Entra ID managed identity.

  • Authorization - For more fine-grained access control, preauthorize requests that pass OAuth 2.0 tokens generated by an identity provider such as Microsoft Entra ID.

For background, see:

Prerequisites

Before following the steps in this article, you must have:

  • An API Management instance. For example steps, see Create an Azure API Management instance.
  • An Azure OpenAI resource and model added to your API Management instance. For example steps, see Import an Azure OpenAI API as a REST API.
  • Permissions to create an app registration in an identity provider such as a Microsoft Entra tenant associated with your Azure subscription (for OAuth 2.0 authorization).

Authenticate with API key

A default way to authenticate to an Azure OpenAI API is by using an API key. For this type of authentication, all API requests must include a valid API key in the api-key HTTP header.

  • API Management can manage the API key in a secure way, by using a named value.
  • The named value can then be referenced in an API policy to set the api-key header in requests to the Azure OpenAI API. We provide two examples of how to do this: one uses the set-backend-service policy, and the other uses the set-header policy.

Store the API key in a named value

  1. Obtain an API key from the Azure OpenAI resource. In the Azure portal, find a key on the Keys and Endpoint page of the Azure OpenAI resource.
  2. Go to your API Management instance, and select Named values in the left menu.
  3. Select + Add, and add the value as a secret, or optionally for more security, use a key vault reference.

Pass the API key in API requests - set-backend-service policy

  1. Create a backend that points to the Azure OpenAI API.

    1. In the left menu of your API Management instance, select Backends.
    2. Select + Add, and enter a descriptive name for the backend. Example: openai-backend.
    3. Under Type, select Custom, and enter the URL of the Azure OpenAI endpoint. Example: https://contoso.openai.azure.com/openai.
    4. Under Authorization credentials, select Headers, and enter api-key as the header name and the named value as the value.
    5. Select Create.

  2. Add the following set-backend-service policy snippet in the inbound policy section to pass the API key in requests to the Azure OpenAI API.

    In this example, the backend resource is openai-backend.

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

Pass the API key in API requests - set-header policy

Alternatively, add the following set-header policy snippet in the inbound policy section to pass the API key in requests to the Azure OpenAI API. This policy snippet sets the api-key header with the named value that you set up.

In this example, the named value in API Management is openai-api-key.

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

Authenticate with managed identity

An alternative and recommended way to authenticate to an Azure OpenAI API is by using a managed identity in Microsoft Entra ID. For background, see How to configure Azure OpenAI Service with managed identity.

Following are steps to configure your API Management instance to use a managed identity to authenticate requests to an Azure OpenAI API.

  1. Enable a system-assigned or user-assigned managed identity for your API Management instance. The following example assumes that you've enabled the instance's system-assigned managed identity.

  2. Assign the managed identity the Cognitive Services OpenAI User role, scoped to the appropriate resource. For example, assign the system-assigned managed identity the Cognitive Services OpenAI User role on the Azure OpenAI resource. For detailed steps, see Role-based access control for Azure OpenAI service.

  3. Add the following policy snippet in the inbound policy section to authenticate requests to the Azure OpenAI API using the managed identity.

    In this example:

    XML 
    <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 authorization using identity provider

To enable more fine-grained access to OpenAPI APIs by particular users or clients, you can preauthorize access to the Azure OpenAI API using OAuth 2.0 authorization with Microsoft Entra ID or another identity provider. For background, see Protect an API in Azure API Management using OAuth 2.0 authorization with Microsoft Entra ID.

Note

Use OAuth 2.0 authorization as part of a defense-in-depth strategy. It's not a replacement for API key authentication or managed identity authentication to an Azure OpenAI API.

Following are high level steps to restrict API access to users or apps that are authorized using an identity provider.

  1. Create an application in your identity provider to represent the OpenAI API in Azure API Management. If you're using Microsoft Entra ID, register an application in your Microsoft Entra ID tenant. Record details such as the application ID and the audience URI.

    As needed, configure the application to have roles or scopes that represent the fine-grained permissions needed to access the Azure OpenAI API.

  2. Add an inbound policy snippet in your API Management instance to validate requests that present a JSON web token (JWT) in the Authorization header. Place this snippet before other inbound policies that you set to authenticate to the Azure OpenAI API.

    Note

    The following examples show the general structure of the policies to validate a JWT. Customize them to your identity provider and the requirements of your application and API.

    • validate-azure-ad-token - If you use Microsoft Entra ID, configure the validate-azure-ad-token policy to validate the audience and claims in the JWT. For details, see the policy reference.

      XML 
      <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 - If you use another identity provider, configure the validate-jwt policy to validate the audience and claims in the JWT. For details, see the policy reference.

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

Related content