[Feature] Azure CLI Authentication for Azure OpenAI

[shubhamdeodia]

What Would You Like to See with the Gateway?

Overview

This feature adds support for Azure CLI-based authentication to the Portkey AI Gateway for Azure OpenAI and Azure AI Inference services. This allows developers to authenticate using their Azure CLI credentials without managing API keys or configuring complex service principal workflows.

Motivation

Current Authentication Methods

The gateway currently supports the following Azure authentication modes:

• apiKey: Direct API key authentication
• entra: Entra ID (formerly Azure AD) with client credentials (requires client_id, client_secret, tenant_id)
• managed: Managed Identity (for Azure-hosted resources)
• workload: Workload Identity (for Kubernetes environments)

Why Azure CLI Authentication?

Azure CLI authentication offers several benefits:

1. Developer Experience: Developers already authenticated with az login can use the gateway without additional credentials
2. Local Development: Simplifies local development workflows - no need to create or manage service principals for dev/test
3. Security: Leverages Azure CLI's secure credential storage and token management
4. Compliance: Uses the same authentication as other Azure tools, maintaining consistent security posture
5. Temporary Access: Perfect for temporary or development scenarios where long-lived credentials are not desired

Use Cases

1. Local Development

Developers working on AI applications can test against Azure OpenAI using their existing Azure CLI credentials:

# One-time login
az login

# Use the gateway with CLI auth
npx @portkey-ai/gateway

2. CI/CD Pipelines

CI/CD systems already authenticated with Azure CLI can use the gateway without managing additional secrets:

- name: Login to Azure
  run: az login --service-principal -u $AZURE_CLIENT_ID -p $AZURE_CLIENT_SECRET -t $AZURE_TENANT_ID

- name: Run tests with Portkey Gateway
  run: npm test
  env:
    AZURE_AUTH_MODE: azure_cli

3. Multi-Developer Environments

Teams can standardize on Azure CLI authentication, allowing each developer to use their own credentials without sharing API keys.

4. Short-lived Testing

Quick prototyping and testing scenarios where setting up service principals is overhead:

from portkey_ai import Portkey

# No API keys needed - uses Azure CLI credentials
client = Portkey(
    provider="azure-openai",
    config={
        "azure_auth_mode": "azure_cli",
        "resource_name": "my-openai-resource",
        "deployment_id": "gpt-4",
        "api_version": "2024-02-15-preview"
    }
)

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello!"}],
    model="gpt-4"
)

Configuration

Gateway Configuration (JSON)

{
  "provider": "azure-openai",
  "resource_name": "my-openai-resource",
  "deployment_id": "gpt-4",
  "api_version": "2024-02-15-preview",
  "azure_auth_mode": "azure_cli"
}

Environment Setup

# Login to Azure CLI
az login

# Optionally set default subscription
az account set --subscription "my-subscription-id"

# Run the gateway
npx @portkey-ai/gateway

SDK Usage Examples

Python:

from portkey_ai import Portkey

client = Portkey(
    provider="azure-openai",
    config={
        "azure_auth_mode": "azure_cli",
        "resource_name": "my-openai-resource",
        "deployment_id": "gpt-4",
        "api_version": "2024-02-15-preview"
    }
)

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello from Azure CLI auth!"}],
    model="gpt-4"
)
print(response.choices[0].message.content)

Node.js:

const Portkey = require('portkey-ai');

const client = new Portkey({
  provider: "azure-openai",
  config: {
    azure_auth_mode: "azure_cli",
    resource_name: "my-openai-resource",
    deployment_id: "gpt-4",
    api_version: "2024-02-15-preview"
  }
});

const response = await client.chat.completions.create({
  messages: [{ role: "user", content: "Hello from Azure CLI auth!" }],
  model: "gpt-4"
});

Prerequisites

System Requirements

• Azure CLI: Must be installed and available in PATH
• Authentication: User must be logged in via az login
• Runtime: Node.js environment (not supported in serverless/edge runtimes)
• Permissions: Azure account must have appropriate permissions for Azure OpenAI resource

Installation

# Install Azure CLI (if not already installed)
# macOS
brew install azure-cli

# Windows
winget install Microsoft.AzureCLI

# Linux
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Verify installation
az --version

# Login
az login

Error Handling

The implementation includes comprehensive error handling:

1. Azure CLI Not Installed

   Error: getAzureCliToken error: Command 'az' not found
   Make sure Azure CLI is installed and you are logged in using "az login"
   

2. Not Logged In

   Error: Please run 'az login' to authenticate
   

3. Insufficient Permissions

   Error: Access denied to Azure Cognitive Services
   

Limitations

1. Runtime Restriction: Only works in Node.js runtime (not Cloudflare Workers, Deno, or other serverless platforms)
2. Performance: Slight overhead from executing CLI command (~100-300ms for first token request)
3. Token Refresh: Tokens expire after 1 hour; Azure CLI handles refresh automatically
4. Local Development: Primarily designed for local development and testing scenarios

Security Considerations

1. Token Scope: Tokens are scoped to https://cognitiveservices.azure.com/ resource
2. Token Lifetime: Follows Azure CLI token lifetime policies (typically 1 hour)
3. Credential Storage: Leverages Azure CLI's secure credential storage mechanisms
4. Audit Trail: Authentication events are logged through Azure's audit systems

Comparison with Other Auth Modes

Auth Mode	Use Case	Complexity	Token Management
apiKey	Production	Low	Manual
entra	Production	Medium	Automatic (OAuth2)
managed	Azure VMs	Low	Automatic (IMDS)
workload	Kubernetes	Medium	Automatic (K8s)
azure_cli	Local Dev	Low	Automatic (CLI)

Migration Path

Existing users can easily migrate to Azure CLI authentication:

Before:

{
  "provider": "azure-openai",
  "api_key": "sk-***",
  "resource_name": "my-resource",
  "deployment_id": "gpt-4",
  "api_version": "2024-02-15-preview"
}

After:

{
  "provider": "azure-openai",
  "azure_auth_mode": "azure_cli",
  "resource_name": "my-resource",
  "deployment_id": "gpt-4",
  "api_version": "2024-02-15-preview"
}

Future Enhancements

1. Token Caching: Cache tokens to reduce CLI execution overhead
2. Custom Scopes: Support custom resource scopes beyond Cognitive Services
3. Subscription Selection: Allow specifying subscription ID for multi-subscription scenarios
4. Tenant Selection: Support multi-tenant scenarios

References

• Azure CLI Authentication
• Azure OpenAI Authentication
• Azure Identity Documentation

Context for your Request

This feature request enhances developer experience by providing a seamless authentication method that leverages existing Azure CLI credentials. It reduces the barrier to entry for developers who want to test and develop with Azure OpenAI through the Portkey Gateway without the overhead of managing additional credentials.

The implementation is straightforward, secure, and follows Azure's best practices for authentication. It's particularly valuable for local development, testing, and CI/CD scenarios where Azure CLI is already the primary tool for Azure resource management.

[shubhamdeodia]

#1426