Support for Microsoft Entra ID with Azure OpenAI interface

[pablospe]

Compared regular API key authentication, for example, with OpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
)

With Microsoft Entra ID authentication, there is not explicit API key we need to manage anymore, increasing the security and convenience. For example:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

api_version = "2024-07-01-preview"
endpoint = "https://my-resource.openai.azure.com"

client = AzureOpenAI(
    api_version=api_version,
    azure_endpoint=endpoint,
    azure_ad_token_provider=token_provider,
)

I was wondering if there is a plan to support Microsoft Entra ID. Thanks!

[pablospe]

It might be similar to the following PR? https://github.com/567-labs/instructor/pull/1633/files

[jxnl]

@claude can you propose a solution and a PR

[claude]

Claude finished @jxnl's task —— View job • Create PR ➔

---

Microsoft Entra ID Support Implementation Complete! 🎉

I've successfully implemented Microsoft Entra ID authentication support for Azure OpenAI interface. This enables token-based authentication instead of API keys for enhanced security.

Implementation Summary

✅ Core Implementation (instructor/auto_client.py):

• Added azure_ad_token_provider parameter support
• Maintains full backwards compatibility with API key authentication
• Supports both sync and async Azure OpenAI clients
• Clear error messages guide users on authentication options

✅ Comprehensive Documentation (docs/integrations/azure.md):

• Added Microsoft Entra ID authentication section with examples
• Shows both DefaultAzureCredential and ManagedIdentityCredential usage
• Updated all relevant sections including auto client examples
• Provided side-by-side API key vs Entra ID comparisons

✅ Test Coverage (tests/test_azure_entra_id.py):

• Tests for both authentication methods
• Backwards compatibility verification
• Error handling for missing configuration
• Async client support validation
• API version and endpoint configuration tests

Usage Examples

Basic Microsoft Entra ID Usage:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import instructor

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://cognitiveservices.azure.com/.default"
)

client = instructor.from_provider(
    "azure_openai/gpt-4o-mini",
    azure_ad_token_provider=token_provider,
    azure_endpoint="https://your-resource.openai.azure.com/"
)

Enterprise/Managed Identity Usage:

from azure.identity import ManagedIdentityCredential, get_bearer_token_provider

credential = ManagedIdentityCredential()
token_provider = get_bearer_token_provider(
    credential, 
    "https://cognitiveservices.azure.com/.default"
)

client = instructor.from_provider(
    "azure_openai/gpt-4o-mini",
    azure_ad_token_provider=token_provider,
    azure_endpoint="https://your-resource.openai.azure.com/"
)

Benefits for Enterprise Users

• 🔐 Enhanced Security: No API keys to manage or expose
• 🏢 Enterprise Integration: Leverages existing Azure AD/Entra ID infrastructure
• 🔄 Flexible Authentication: Supports managed identity, service principals, user credentials
• 📋 Compliance Ready: Works with Azure AD policies and conditional access
• 🔄 Backwards Compatible: Existing API key authentication continues to work

Ready for PR Creation

All changes have been staged and are ready for commit. To complete the PR:

# Commit the changes
git commit -m "feat(azure): add Microsoft Entra ID authentication support

Add support for Microsoft Entra ID authentication for Azure OpenAI clients alongside existing API key authentication. This enables enterprise users to leverage Azure AD/Entra ID for secure, keyless authentication.

Changes:
- Add azure_ad_token_provider parameter support in auto_client.py
- Update Azure OpenAI documentation with Entra ID examples
- Add comprehensive test coverage for both auth methods
- Maintain full backwards compatibility with API key auth

Resolves #1692

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-authored-by: Jason Liu <jxnl@users.noreply.github.com>"

# Push to remote
git push origin claude/issue-1692-20250711_163927

[jxnl]

@claude make the PR

[claude]

Claude finished @jxnl's task —— View job

---

Microsoft Entra ID Support Implementation Complete! 🎉

I've successfully implemented Microsoft Entra ID authentication support for Azure OpenAI interface. The implementation is complete and ready for PR creation.

Implementation Summary

✅ Core Implementation (instructor/auto_client.py):

• Added azure_ad_token_provider parameter support
• Maintains full backwards compatibility with API key authentication
• Supports both sync and async Azure OpenAI clients
• Clear error messages guide users on authentication options

✅ Comprehensive Documentation (docs/integrations/azure.md):

• Added Microsoft Entra ID authentication section with examples
• Shows both DefaultAzureCredential and ManagedIdentityCredential usage
• Updated all relevant sections including auto client examples
• Provided side-by-side API key vs Entra ID comparisons

✅ Test Coverage (tests/test_azure_entra_id.py):

• Tests for both authentication methods
• Backwards compatibility verification
• Error handling for missing configuration
• Async client support validation
• API version and endpoint configuration tests

Usage Examples

Basic Microsoft Entra ID Usage:

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import instructor

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://cognitiveservices.azure.com/.default"
)

client = instructor.from_provider(
    "azure_openai/gpt-4o-mini",
    azure_ad_token_provider=token_provider,
    azure_endpoint="https://your-resource.openai.azure.com/"
)

Enterprise/Managed Identity Usage:

from azure.identity import ManagedIdentityCredential, get_bearer_token_provider

credential = ManagedIdentityCredential()
token_provider = get_bearer_token_provider(
    credential, 
    "https://cognitiveservices.azure.com/.default"
)

client = instructor.from_provider(
    "azure_openai/gpt-4o-mini",
    azure_ad_token_provider=token_provider,
    azure_endpoint="https://your-resource.openai.azure.com/"
)

Benefits for Enterprise Users

• 🔐 Enhanced Security: No API keys to manage or expose
• 🏢 Enterprise Integration: Leverages existing Azure AD/Entra ID infrastructure
• 🔄 Flexible Authentication: Supports managed identity, service principals, user credentials
• 📋 Compliance Ready: Works with Azure AD policies and conditional access
• 🔄 Backwards Compatible: Existing API key authentication continues to work

Ready for PR Creation

All changes have been staged and are ready for commit. The implementation includes proper error handling, comprehensive documentation, and test coverage while maintaining full backwards compatibility.

Note: Unable to commit directly due to bash permissions, but all files are ready. A maintainer can complete the commit and push, or bash permissions can be granted to finish the PR creation.

Create PR

[jxnl]

@pablospe can you take a look at #1703 and verify? I dont have these credentials not sure if you're able to test

[pablospe]

Thanks!

I tested the last release this way (from azure.md in the commit)

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI
import instructor
import os

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    api_version="2024-07-01-preview",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
)
client = instructor.from_openai(client, model="gpt-4o-mini")

And I confirm this way is working for me, so I don't need to deal with API keys anymore :) Although, I haven't tested the new interface yet. Is there a python wheel artifact from this PR that I could download, install and test.

Btw, I didn't realize I could have done this before, so it is good that now it will be documented. In a sense, this feature was supported already. Thanks for the awesome library!