Azure OpenAI Upstream

In this guide, you will route AISIX AI Gateway to Azure OpenAI Service. Callers can reach Azure deployments through the gateway's OpenAI-compatible API.

This configuration is for Azure OpenAI deployments that should use AISIX authentication, model allowlists, rate limits, and usage accounting. AISIX can authenticate upstream with a resource API key or an Entra ID client credential.

Prerequisites

Before starting, prepare the following:

• A gateway with the admin API on :3001 and the proxy API on :3000.
• The admin key from the gateway config.yaml.
• An Azure OpenAI resource with a deployment.
• Either a resource API key or an Entra ID app registration with tenant_id, client_id, and client_secret granted access to the resource.
• The Azure OpenAI resource host, deployment name, and caller-facing alias.

Configure the Azure Upstream

Create an Azure provider key, model alias, and caller API key. Both Azure authentication schemes use the same model and caller API-key resources; only the provider-key secret differs.

Create an Azure Provider Key

Choose the authentication scheme that matches how your Azure OpenAI resource is managed.

Use Resource API Key Authentication

Use this option when your Azure OpenAI resource is managed with a resource API key:

export AISIX_ADMIN_KEY="admin-local-only-change-me"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "azure-prod",
    "provider": "azure",
    "adapter": "azure-openai",
    "secret": "YOUR_AZURE_API_KEY",
    "api_base": "https://acme-west.openai.azure.com"
  }'

❶ provider labels the upstream.

❷ adapter selects Azure OpenAI.

❸ secret stores the Azure OpenAI resource API key.

❹ api_base points to the Azure OpenAI resource host. AISIX also accepts the bare resource name, such as acme-west.

Use Entra ID Authentication

Use this option when your Azure OpenAI resource should be accessed through an Entra ID app registration:

export AISIX_ADMIN_KEY="admin-local-only-change-me"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "azure-aad-prod",
    "provider": "azure",
    "adapter": "azure-openai",
    "secret": "{\"tenant_id\":\"YOUR_TENANT_ID\",\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}",
    "api_base": "https://acme-west.openai.azure.com"
  }'

❶ provider labels the upstream.

❷ adapter selects Azure OpenAI.

❸ secret must include tenant_id, client_id, and client_secret. The client_secret value is the secret value, not the secret ID.

❹ api_base points to the Azure OpenAI resource host. AISIX also accepts the bare resource name, such as acme-west.

Provider key secrets follow the credential-handling behavior described in Provider Keys.

For national or sovereign clouds, add authority_host to the JSON secret. Omit it for public Azure. The value must be a bare HTTP(S) origin, such as https://login.microsoftonline.us.

Save the returned provider key ID for the model resource.

Create a Model

Map a caller-facing alias to the Azure deployment name:

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-azure",
    "provider": "azure",
    "model_name": "gpt4o-prod",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

❶ provider uses the same label as the provider key.

❷ model_name is the Azure deployment name, not the underlying model ID.

❸ provider_key_id attaches the model to the Azure credential.

AISIX builds the outbound chat-completions URL from the provider key's api_base and the model's model_name:

https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-10-21

Create a Caller API Key

Choose the plaintext caller API key that the application will send to AISIX, then hash it for the admin resource:

export AISIX_API_KEY="sk-azure-caller"

CALLER_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

Create the API key resource with access to the Azure-backed model alias:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["gpt-4o-azure"]
  }'

❶ allowed_models must match the model alias you created.

Verify the Upstream

Send a chat-completions request through the AISIX proxy. The request is identical regardless of which upstream authentication scheme the provider key uses.

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-azure",
    "messages": [
      {"role": "user", "content": "Say hello from Azure OpenAI."}
    ]
  }'

The gateway returns an OpenAI-compatible response with the caller-facing alias:

{
  "id": "cmpl_azure_example",
  "object": "chat.completion",
  "model": "gpt-4o-azure",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from Azure OpenAI!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 5,
    "total_tokens": 12
  }
}

For a resource API-key provider key, AISIX sends the Azure api-key header. For an Entra ID provider key, AISIX sends Authorization: Bearer <token>.

Check Azure OpenAI metrics, logs, or quota usage for the test request. If AISIX returns an upstream authentication error, check the resource API key or Entra ID credential. If it returns an upstream route error, check api_base, the deployment name in model_name, and the Azure API version supported by your deployment.

Before Production

AISIX currently sends Azure OpenAI requests with api-version=2024-10-21. Confirm that this API version is supported by your Azure OpenAI deployment and track Azure's API version deprecation schedule.

Azure may attach prompt_filter_results and content_filter_results to successful responses. AISIX accepts these Azure extension fields and returns the standard OpenAI-compatible response to the caller.

For a corporate proxy, private endpoint, or test endpoint, set api_base to the exact host AISIX should call. AISIX appends the Azure deployment path and rejects query strings, fragments, and embedded user information.

Next Steps

You have now configured Azure OpenAI as an upstream provider family. Use the same pattern for other Azure deployments by changing the resource host, credential, deployment name, and caller-facing alias.