Skip to main content

Setup Azure OpenAI Model Deployment and Authentication

Overview​

This guide explains how to:

  1. Create an Azure OpenAI resource

  2. Deploy a model in Azure AI Foundry (or the Azure OpenAI deployment UX)

  3. Copy the correct API endpoint(s)

  4. Configure authentication:

    • API Key

    • Microsoft Entra ID (Service Principal / client credentials)

Step 1 — Create an Azure OpenAI resource​

  1. In Azure Portal, create a new Azure OpenAI (Azure AI Foundry / OpenAI) resource.

  2. Choose subscription, resource group, and region.

  3. Once created, open the resource and locate:

    • Endpoint

    • Keys (if using API key auth)

Step 2 — Create model deployments in Azure AI Foundry​

  1. Open Azure AI Foundry for your resource.

  2. Create a deployment for the model you want (for example a GPT model).

  3. Record:

    • Deployment name (used in the URL for chat completions)

    • Model name (used for Responses API depending on your pattern)

Azure supports both Chat Completions and Responses API usage patterns.

Step 3 — Copy the API endpoint URL​

You will typically use one of these URL styles:

Chat Completions endpoint style​

https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=YYYY-MM-DD[-preview]

Responses API endpoint style​

https://{resource}.openai.azure.com/openai/responses?api-version=YYYY-MM-DD[-preview]

Your adapter/library's checkEndpoint() function uses this URL to determine which API to call automatically.

Step 4 — Authentication option A: API Key​

  1. In the Azure OpenAI resource, go to Keys and Endpoint.

  2. Copy KEY 1 (or KEY 2).

  3. In Iguana component configuration:

    • AuthMode = api_key

    • ApiKey = copied key

Step 5 — Authentication option B: Microsoft Entra ID (Service Principal)​

This option uses OAuth2 client credentials and Azure RBAC. Microsoft documents assigning roles like Cognitive Services OpenAI User (or Contributor) to the identity that will call the API.

5.1 Create an App Registration​

  1. Go to Microsoft Entra ID → App registrations → New registration

  2. Name it (example: Iguana-AzureOpenAI)

  3. After creation, copy:

    • Application (client) ID

    • Directory (tenant) ID

5.2 Create a Client Secret​

  1. App registration → Certificates & secrets → New client secret

  2. Copy the secret value immediately (you won't be able to retrieve it again)

5.3 Assign Azure RBAC role on the Azure OpenAI resource​

  1. Go to your Azure OpenAI resource → Access control (IAM)

  2. Add role assignment

  3. Choose one of (commonly):

    • Cognitive Services OpenAI User

    • Cognitive Services OpenAI Contributor

  4. Assign it to the App Registration (service principal)

5.4 Configure Iguana component​

Set:

  • AuthMode = entra_id

  • AzureTenantId = tenant ID

  • AzureClientId = client ID

  • AzureClientSecret = client secret value

  • ApiEndpoint = your endpoint URL

5.5 Token scope used by the library​

The common Entra token scope for Azure Cognitive Services is:

https://cognitiveservices.azure.com/.default

Troubleshooting​

  • 401 Unauthorized

    • Verify role assignment exists on the Azure OpenAI resource for the service principal.

  • 403 Forbidden

    • Role exists but may be assigned at wrong scope (resource group vs resource), or propagation delay.

  • Unsupported parameter / Unsupported value

    • The library retries automatically by removing parameters like temperature and top_p when Azure rejects them.