This document provides comprehensive guidance for Azure MCP Server authentication and related security considerations in enterprise environments. While the core focus is authentication, it also covers network and security configurations that commonly affect authentication in enterprise scenarios.

Azure MCP Server authenticates to Microsoft Entra ID via the Azure Identity library for .NET.

The server supports two authentication modes: broker mode (which uses your OS's native authentication system like Windows Web Account Manager for enhanced security) and credential chain mode (which tries multiple authentication methods in sequence). Here is an overview of how authentication works:

flowchart TD
    C{"Broker mode?"} -- yes --> D["OS broker"]
    C -- no --> E["EnvironmentCredential"]
    E -- failed --> n8["VisualStudioCredential"]
    E -- succeeded --> n17["Authenticated to Azure"]
    n8 -- failed --> n12["AzureCliCredential"]
    n8 -- succeeded --> n17
    n12 -- failed --> n13["AzurePowerShellCredential"]
    n12 -- succeeded --> n17
    n13 -- failed --> n14["AzureDeveloperCliCredential"]
    n13 -- succeeded --> n17
    n14 -- failed --> n15["InteractiveBrowserCredential"]
    n14 -- succeeded --> n17
    n15 -- failed --> n16["Authentication failed"]
    n15 -- succeeded --> n17
    n17@{ shape: event }
    n16@{ shape: event }

If environment variable AZURE_MCP_ONLY_USE_BROKER_CREDENTIAL is:

• Set to true, a broker-enabled instance of InteractiveBrowserCredential is used to authenticate. On Windows, the broker is Web Account Manager. If a broker isn't supported on your operating system, the credential degrades gracefully to a browser-based login experience. For more information on this approach, see Interactive brokered authentication.

• Not set, a custom chain of credentials is used to authenticate. The chain is designed to support many environments, along with the most common authentication flows and developer tools. When one credential fails to acquire a token, the chain attempts the next credential. In Azure MCP Server, the chain is configured as follows by default:

  Order	Credential	Description	Enabled?
  1	EnvironmentCredential	Perfect for CI/CD pipelines	Yes
  2	WorkloadIdentityCredential	Uses Workload ID authentication on Kubernetes and other hosts supporting workload identity	No
  3	ManagedIdentityCredential	Uses managed identity authentication	No
  4	VisualStudioCredential	Uses your Visual Studio login	Yes
  5	AzureCliCredential	Uses your Azure CLI login	Yes
  6	AzurePowerShellCredential	Uses your Azure PowerShell login	Yes
  7	AzureDeveloperCliCredential	Uses your Azure Developer CLI login	Yes
  8	InteractiveBrowserCredential	Uses a broker and falls back to browser-based login if needed. The account picker dialog allows you to ensure you're selecting the correct account.	Yes

  Note: InteractiveBrowserCredential is included as a fallback only in default and "dev" credential chains. When using AZURE_TOKEN_CREDENTIALS=prod or specifying a specific credential, the interactive browser credential is not added, ensuring production scenarios fail fast if authentication is unavailable.

  If you're logged in through any of these mechanisms, the Azure MCP Server will automatically use those credentials. Ensure that you have the correct authorization permissions in Azure. For example, read access to your Storage account via Role-Based Access Control (RBAC). To learn more about Azure's RBAC authorization system, see What is Azure RBAC?.

For Kubernetes workloads or Azure-hosted apps (Web Apps, Function Apps, Container Apps, AKS), set the following environment variable:

export AZURE_TOKEN_CREDENTIALS=prod

This configuration modifies the credential chain to use only production credentials (Environment, Workload Identity, and Managed Identity), in that order. The InteractiveBrowserCredential is NOT included, ensuring authentication fails fast if none of the production credentials are available.

For User-Assigned Managed Identity, also set:

export AZURE_CLIENT_ID=<your-managed-identity-client-id>

If AZURE_CLIENT_ID is not set, System-Assigned Managed Identity will be used.

For local development with minimal restrictions, authenticate using Visual Studio, Azure CLI, Azure PowerShell, or Azure Developer CLI. For example, run the following commands to authenticate via Azure CLI:

az login
# Verify access
az account show

The default credential chain includes InteractiveBrowserCredential as a fallback for development convenience.

For automated builds and deployments, set the following environment variables:

# Use service principal
export AZURE_CLIENT_ID="<pipeline-sp-client-id>"
export AZURE_CLIENT_SECRET="<pipeline-sp-secret>"
export AZURE_TENANT_ID="<your-tenant-id>"

Many organizations disable local authentication methods (access keys, SAS tokens) on their Azure resources for security compliance. This affects resources like:

• Azure Storage accounts
• Azure Cosmos DB
• Azure Key Vault (in some configurations)
• Azure Service Bus
• Azure Event Hubs

When local authentication is disabled, Azure MCP Server must use Microsoft Entra authentication exclusively. This requires:

1. Proper RBAC permissions on the target resources
2. Network connectivity to Microsoft Entra endpoints
3. Valid Microsoft Entra ID credentials (not personal Microsoft accounts)

Information to Provide to Your Admin:

1. Service Principal Requirements:

   Application Name: Azure MCP Server Access
   Required Permissions:
   - Resource-specific data plane roles (e.g., Storage Blob Data Reader)
   - Subscription/Resource Group reader permissions (for discovery)
   

2. Network Requirements:

   Required Endpoints:
   - login.microsoftonline.com (Microsoft Entra authentication)
   - management.azure.com (Azure Resource Manager)
   - Resource-specific endpoints (e.g., *.blob.core.windows.net)
   

3. RBAC Role Assignments Needed:

   Scope: Subscription, Resource Group, or specific Resource
   Principal: Your user account or service principal
   Roles: Service-specific data plane roles
   

Questions to Ask Your Admin:

• Is local authentication disabled on the target resources?
• What RBAC roles are available for data plane access?
• Are there any Conditional Access policies that might block authentication?
• Is there a preferred authentication method (user vs. service principal)?
• Are there network restrictions (private endpoints, firewall rules)?

Azure Cosmos DB supports data plane access via Microsoft Entra ID (RBAC). If key-based authentication is disabled (recommended), grant a Microsoft Entra user or service principal a built-in data role at the Cosmos account scope.

Prerequisites:

• Azure CLI installed (az version)
• Logged in to the correct tenant/subscription (az login)
• Resource group and account name for the Cosmos DB account

Role options (built-in):

• Data Contributor: full read/write data access — role ID 00000000-0000-0000-0000-000000000002
• Data Reader: read-only data access — role ID 00000000-0000-0000-0000-000000000001

PowerShell example (assign Data Contributor to a user):

$user = 'user@contoso.com'
$resourceGroup = 'rg-name'
$account = 'cosmos-account-name'

# Account scope
$resourceId = az cosmosdb show -g $resourceGroup -n $account --query "id" -o tsv

# Built-in Data Contributor role
$roleId = az cosmosdb sql role definition show -a $account -g $resourceGroup -i 00000000-0000-0000-0000-000000000002 --query id -o tsv

# Principal object ID (user)
$principalId = az ad user show --id $user --query 'id' -o tsv

az cosmosdb sql role assignment create --resource-group $resourceGroup --account-name $account --principal-id $principalId --role-definition-id $roleId --scope $resourceId

Bash example (assign Data Reader to a service principal):

spAppId="00000000-0000-0000-0000-000000000000" # replace with your app (client) ID
resourceGroup="rg-name"
account="cosmos-account-name"

# Account scope
resourceId=$(az cosmosdb show -g "$resourceGroup" -n "$account" --query id -o tsv)

# Built-in Data Reader role
roleId=$(az cosmosdb sql role definition show -a "$account" -g "$resourceGroup" -i 00000000-0000-0000-0000-000000000001 --query id -o tsv)

# Principal object ID (service principal)
principalId=$(az ad sp show --id "$spAppId" --query id -o tsv)

az cosmosdb sql role assignment create \
  --resource-group "$resourceGroup" \
  --account-name "$account" \
  --principal-id "$principalId" \
  --role-definition-id "$roleId" \
  --scope "$resourceId"

Notes:

• Scope can be set at the account level (as above) or narrowed to database/container scopes if needed.
• RBAC propagation may take several minutes after assignment.
• Use the Reader role for read-only scenarios and Contributor for read/write tooling.
• Ensure you authenticate via one of the supported credentials (for example, Azure CLI — az login) before using Cosmos tools in Azure MCP.

Organizations often implement network restrictions that can affect Azure MCP Server's ability to authenticate and access resources. While these are network security configurations, they directly impact authentication flows.

1. Corporate Firewalls

   • Outbound HTTPS filtering
   • Proxy server requirements
   • Limited allowed domains

2. Azure Firewall Rules

   • IP address restrictions on Azure resources
   • Virtual network integration requirements
   • Private endpoint configurations

3. Conditional Access Policies

   • Device compliance requirements
   • Location-based restrictions
   • Multi-factor authentication requirements

Essential Endpoints for Authentication:

login.microsoftonline.com:443
login.windows.net:443
management.azure.com:443
graph.microsoft.com:443

Resource-Specific Endpoints:

Storage: *.blob.core.windows.net:443, *.table.core.windows.net:443
Key Vault: *.vault.azure.net:443
Cosmos DB: *.documents.azure.com:443
Service Bus: *.servicebus.windows.net:443

Working with Network Administrators:

1. Request Firewall Rules:

   Source: Your IP address or network range
   Destination: Azure service endpoints (see above)
   Protocol: HTTPS (TCP/443)
   

2. Proxy Configuration:

   # Set proxy environment variables if required
   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   export NO_PROXY=localhost,127.0.0.1

3. Corporate Certificate Trust:

   • Ensure corporate CA certificates are trusted
   • May require certificate bundle updates

When Azure resources are configured with private endpoints, authentication flows require additional network configuration to reach the authentication endpoints.

Private endpoints require proper DNS resolution:

# Verify DNS resolution for private endpoints
nslookup mystorageaccount.blob.core.windows.net
# Should resolve to private IP (10.x.x.x range)

Ensure your development environment can reach the private endpoint:

1. VPN Connection to the corporate network
2. ExpressRoute connectivity
3. Point-to-site VPN configuration
4. Bastion Host or jump server access

Information to Provide:

1. Resource Details:

   Resource Name: mystorageaccount
   Private Endpoint Name: mystorageaccount-pe
   Required DNS Zone: privatelink.blob.core.windows.net
   

2. Network Requirements:

   Source Network: Developer workstation network
   Destination Network: Private endpoint subnet
   Ports: TCP/443 for HTTPS
   

For automated scenarios or when interactive authentication isn't possible due to security policies:

Work with your Azure administrator to create a service principal:

# Admin runs this command
az ad sp create-for-rbac --name "azure-mcp-server" --role "Reader" --scopes "/subscriptions/{subscription-id}"

Set environment variables for service principal authentication:

export AZURE_CLIENT_ID="<your-client-id>"
export AZURE_CLIENT_SECRET="<your-client-secret>"
export AZURE_TENANT_ID="<your-tenant-id>"

1. Least Privilege: Only assign necessary permissions
2. Secret Rotation: Regularly rotate client secrets
3. Certificate Authentication: Prefer certificates over secrets when possible
4. Monitoring: Enable audit logging for service principal usage

Organizations may enforce Conditional Access policies that affect authentication flows:

1. Device Compliance

   • Device must be Azure AD joined
   • Device must meet compliance policies
   • Intune enrollment may be required

2. Multi-Factor Authentication (MFA)

   • Additional authentication factors required
   • May not work with non-interactive scenarios

3. Location Restrictions

   • Authentication only allowed from specific IP ranges
   • VPN connection may be required

Questions to Ask:

• Are there Conditional Access policies affecting my authentication?
• Is my device compliant with organizational policies?
• Can I get an exception for development scenarios?
• Are there specific authentication methods I should use?

1. Test Authentication:

   az login --tenant your-tenant-id
   az account show

2. Test Resource Access:

   # Test storage access
   az storage blob list --account-name mystorageaccount --container-name mycontainer --auth-mode login

3. Network Connectivity:

   # Test endpoint connectivity
   curl -I https://login.microsoftonline.com
   telnet mystorageaccount.blob.core.windows.net 443

1. DNS Resolution Failures:

   Error: getaddrinfo ENOTFOUND mystorageaccount.privatelink.blob.core.windows.net
   Solution: Configure DNS for private endpoints
   

2. Certificate Trust Issues:

   Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE
   Solution: Install corporate CA certificates
   

3. Firewall Blocks:

   Error: connect ETIMEDOUT
   Solution: Configure firewall rules for Azure endpoints
   

When working with administrators, provide:

1. Specific Error Messages: Include full error text and stack traces
2. Resource Details: Names, regions, and configuration details
3. Network Context: Where you're connecting from and network setup
4. Authentication Method: Which credential type you're trying to use
5. Logs: Relevant log entries showing the authentication attempt

For additional support, see the Troubleshooting Guide. For further assistance, open a GitHub issue.