Skip to content

connect.md

Latest commit

 

History

History
284 lines (191 loc) · 18 KB

connect.md

File metadata and controls

284 lines (191 loc) · 18 KB
Raw

Connection Guide

The connect command and the --connect startup option support multiple authentication methods. The shell automatically selects the appropriate credential type based on the arguments provided.

Credential Decision Tree

The credential type is determined by the first matching rule (top-to-bottom):

Priority Condition Credential Used
1 Endpoint is localhost or 127.0.0.1 Emulator (well-known key)
2 Connection string has AccountKey, or COSMOSDB_SHELL_ACCOUNT_KEY env provides a key Account key
3 --connect-vscode-credential flag provided (startup; hidden on interactive connect) VisualStudioCodeCredential (falls back to next step)
4 COSMOSDB_SHELL_TOKEN env var is set Static access token
5 --managed-identity option provided ManagedIdentityCredential
6 --tenant or --hint option provided (and --azure-cli not set) InteractiveBrowserCredential (with DeviceCodeCredential fallback)
7 --azure-cli (startup: --connect-azure-cli) flag provided AzureCliCredential
8 Endpoint only (no additional arguments) DefaultAzureCredential

Note: Step 3 is primarily a startup option (--connect-vscode-credential); it is also accepted as a hidden option on the interactive connect command.

Note: --azure-cli takes precedence over the priority 6 interactive selection, so combining --azure-cli with --tenant uses AzureCliCredential (honoring the tenant) rather than triggering the browser/device-code flow.

The --authority-host option is honored by the Entra ID credentials that accept it: VisualStudioCodeCredential (priority 3), ManagedIdentityCredential (priority 5), the interactive InteractiveBrowserCredential/DeviceCodeCredential (priority 6), and DefaultAzureCredential (priority 8). It does not affect which credential type is selected, and the static token (priority 4) and account key paths ignore it. AzureCliCredential (priority 7) uses the cloud that the Azure CLI is already configured for, so it does not accept --authority-host; if you supply both, the value is ignored and a warning is printed. Use az cloud set to change the Azure CLI cloud instead.

When to use --azure-cli

--azure-cli selects AzureCliCredential directly, using the identity from your current az login session. This is deterministic: it bypasses the credential chain in DefaultAzureCredential.

Prefer it in environments where a managed identity is present but is not the identity you want. The clearest example is Azure Cloud Shell: DefaultAzureCredential tries ManagedIdentityCredential before AzureCliCredential, and Cloud Shell exposes a live managed-identity (IMDS) endpoint, so token acquisition succeeds and the chain stops there. If that managed identity has no Cosmos DB data-plane RBAC role, requests fail with 403 (Forbidden) even though your signed-in az user has access. --azure-cli skips the managed identity entirely and uses your az identity instead.

# Interactive
connect https://myaccount.documents.azure.com:443/ --azure-cli

# Startup
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-azure-cli

--tenant is honored when supplied (passed to AzureCliCredential as the tenant to authenticate against). ARM context is attached for AzureCliCredential just like the other Entra ID credential flows.

Azure Resource Manager Context

Database and container resource operations (listing, navigating to, creating, deleting, and reading configuration for databases and containers) prefer Azure Resource Manager (ARM) when an ARM context is attached. Item operations always use the Cosmos DB data plane.

ARM context is attached only for Entra ID credential flows: VisualStudioCodeCredential, ManagedIdentityCredential, InteractiveBrowserCredential, DeviceCodeCredential, AzureCliCredential, and DefaultAzureCredential. Account-key connections, emulator connections, and COSMOSDB_SHELL_TOKEN connections do not attach ARM context, so resource operations fall back to the Cosmos DB data plane.

When ARM context is attached, the shell can discover the ARM account by matching the connected data-plane endpoint across accessible subscriptions. For deterministic startup, especially in CI/CD or multi-subscription environments, provide the coordinates explicitly:

connect https://myaccount.documents.azure.com:443/ --tenant=<tenant-id> --subscription=<subscription-id> --resource-group=<resource-group>
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-tenant=<tenant-id> --connect-subscription=<subscription-id> --connect-resource-group=<resource-group>

The account name is inferred from the endpoint hostname (the first segment before .documents.*).

When ARM is in use, the identity needs data-plane RBAC for item operations and Azure management-plane permissions for database/container resources, such as Cosmos DB Operator or equivalent scoped permissions on the account. When falling back to the data plane (account-key, emulator, static token), the connection's existing data-plane authority is used for all commands.

Known limitation: strict native data-plane RBAC with non-Entra connections

Account-key connections, COSMOSDB_SHELL_TOKEN connections, and emulator connections do not attach an ARM context, so resource commands (mkdb, mkcon, rmdb, rmcon, index, container info) fall back to the data plane. If you connect to a real Azure Cosmos DB account that has native data-plane RBAC enforced (key-based and control-plane writes disabled), those commands will be rejected by the service even with a valid static credential, because the request never reaches Azure Resource Manager.

To use resource commands against such an account, connect with an Entra ID credential — --tenant, --managed-identity, --azure-cli, --connect-vscode-credential, or the endpoint-only DefaultAzureCredential form — and (optionally) supply --subscription and --resource-group to skip ARM discovery.

Examples

Account Key

# Full connection string
connect "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=mykey;"

# Key via environment variable
export COSMOSDB_SHELL_ACCOUNT_KEY="myaccountkey"
connect https://myaccount.documents.azure.com:443/

Quote the connection string. A connection string contains ;, which the shell treats as a command separator. If you paste it unquoted, the shell splits it into fragments and reports an unknown-command error pointing at the fragment after the first ;. Wrapping the whole value in quotes (as above) avoids this.

Emulator

# Plain URL — automatically uses well-known emulator key + gateway mode
connect https://localhost:8081

Managed Identity (User-Assigned)

connect https://myaccount.documents.azure.com:443/ --managed-identity=<client-id>

Managed Identity (System-Assigned)

For system-assigned managed identity, no --managed-identity argument is needed. Use the endpoint-only form — DefaultAzureCredential includes ManagedIdentityCredential in its chain automatically:

connect https://myaccount.documents.azure.com:443/

Entra ID (Interactive Browser)

# With tenant ID
connect https://myaccount.documents.azure.com:443/ --tenant=<tenant-id>

# With login hint
connect https://myaccount.documents.azure.com:443/ --hint=user@contoso.com

# With both
connect https://myaccount.documents.azure.com:443/ --tenant=<tenant-id> --hint=user@contoso.com

If browser authentication fails, the shell automatically falls back to device code authentication.

DefaultAzureCredential

When only an endpoint is provided with no additional arguments, the shell uses DefaultAzureCredential. This tries credentials in the following order: Environment, Workload Identity, Managed Identity, Visual Studio, VS Code, Azure CLI, Azure PowerShell, Azure Developer CLI, Interactive Browser.

connect https://myaccount.documents.azure.com:443/

Custom Authority Host

For sovereign clouds or custom Entra environments, use --authority-host:

connect https://myaccount.documents.azure.com:443/ --authority-host=https://login.microsoftonline.us/

When --subscription and --resource-group are supplied, the shell also needs to pick an Azure Resource Manager endpoint for control-plane operations (mkdb, mkcon, rmdb, rmcon, index). It resolves the ARM endpoint in this order:

  1. Match the authority host against the built-in table of known Azure clouds (Public, China, US Gov, Germany).
  2. If no match, match the Cosmos endpoint suffix (e.g. .documents.azure.us) against the same table.
  3. If still no match and the authority host is of the form login.<rest>, derive https://management.<rest> as the ARM endpoint. This covers additional national / sovereign clouds whose ARM metadata follows the login.X → management.X convention (for example login.chinacloudapi.cn → management.chinacloudapi.cn). The Public, US Gov, and Germany clouds deliberately do not follow that pattern, which is why the explicit table is consulted first.
  4. Otherwise default to Azure Public.

COSMOSDB_SHELL_ACCOUNT_KEY Environment Variable

This environment variable provides an account key for authentication:

export COSMOSDB_SHELL_ACCOUNT_KEY="myaccountkey"

If the connection string already contains an AccountKey, the environment variable is ignored.

COSMOSDB_SHELL_TOKEN Environment Variable

This environment variable provides a pre-obtained Entra ID access token (JWT) for authentication. This is intended for single-shot command execution where an external process handles token acquisition.

# Obtain a token with the Cosmos DB RBAC scope, then pass it
export COSMOSDB_SHELL_TOKEN=$(az account get-access-token --resource https://<account>.documents.azure.com --query accessToken -o tsv)
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ -c "cd mydb/mycont; ls -m 5"

The token must be issued for the Cosmos DB RBAC scope (https://<account>.documents.azure.com/.default). The external process is responsible for obtaining a valid token with the correct scope and permissions.

When COSMOSDB_SHELL_TOKEN is set, it takes priority over managed identity, interactive browser, and DefaultAzureCredential — but account keys (from the connection string or COSMOSDB_SHELL_ACCOUNT_KEY) still take priority over it.

Security note: Environment variable values may be visible to other processes on the system. This is standard practice for CI/CD token passing, but avoid setting COSMOSDB_SHELL_TOKEN in shared or untrusted environments.

CLI Startup Options

All connect options are also available as CLI startup arguments:

cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-tenant=<tenant-id>
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-managed-identity=<client-id>
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-azure-cli
cosmosdbshell --connect https://myaccount.documents.azure.com:443/ --connect-subscription=<subscription-id> --connect-resource-group=<resource-group>
cosmosdbshell --connect https://localhost:8081

The hidden --connect-vscode-credential flag enables VisualStudioCodeCredential authentication via the system broker. This is used by the VS Code extension and requires the Azure Resources extension to be signed in. If the credential is unavailable, the shell falls back to COSMOSDB_SHELL_TOKEN and then to subsequent credential steps.

Connection Info

Run connect with no arguments to display the current connection info:

> connect
Connection Information
 Account     myaccount
 Endpoint    https://myaccount.documents.azure.com:443/
 Mode        Direct
 ...

Troubleshooting Connection Failures

When a connection fails, the shell prints the underlying reason in addition to the high-level message, so you can tell whether the failure was an invalid key, an authentication error, or an unreachable endpoint:

Connecting with account key...
Failed to connect to the Cosmos DB account.
  → Response status code does not indicate success: 401 (Unauthorized).
Run with --verbose for full exception details.

Add --verbose to print the full exception, including the stack trace and any inner exceptions, which is useful when diagnosing SDK, network, or credential issues:

cosmosdbshell --verbose --connect https://myaccount.documents.azure.com:443/

In verbose mode the shell also surfaces the service-side coordinates for Cosmos DB request failures up front — the HTTP status and sub-status codes plus the activity id — so an authorization denial (403) can be told apart from a token-acquisition failure or a network/port problem at a glance:

Cosmos DB request failed: HTTP 403 Forbidden, sub-status 5301, activity id 8b1f....

The full exception chain is then printed verbatim, which includes the Cosmos DB error body and diagnostics from CosmosException, and — for DefaultAzureCredential — the aggregated per-credential failure reasons that indicate which link in the chain was used and why each one failed.

The shell also reports when credentials are sourced from the environment. When a key is picked up from COSMOSDB_SHELL_ACCOUNT_KEY, it prints Using the account key from the COSMOSDB_SHELL_ACCOUNT_KEY environment variable. before connecting, and COSMOSDB_SHELL_TOKEN is announced the same way. This makes it clear which credential source was actually used.

Security Considerations

Cosmos Shell is a developer and CI/CD tool, and all supported authentication methods are valid for those use cases. The notes below help you choose the right method for your environment and understand the tradeoffs.

Account Keys

Account keys (including connection strings that contain an AccountKey) grant full, unrestricted access to the entire Cosmos DB account. This includes all databases, containers, and operations — there is no way to scope a key to a subset of resources or to read-only access.

Keys are static shared secrets. If a key is leaked, it remains valid until you manually rotate it on the account. Anyone with the key can read, write, and delete any data.

For production and security-sensitive workloads, Microsoft recommends disabling key-based authentication (disableLocalAuth=true) and using Entra ID with data-plane RBAC instead. RBAC allows least-privilege scoping — for example, granting read-only access to a single container.

Account keys are acceptable when:

  • Connecting to the local emulator (which uses a well-known key by design).
  • Running in a CI/CD pipeline where the key is stored in a secure secret store (e.g., Azure Key Vault, GitHub Actions secrets) and never written to logs.
  • Doing local development against a non-production account.

DefaultAzureCredential Security

DefaultAzureCredential is the most convenient option for development — it automatically tries multiple credential sources (Azure CLI, VS Code, managed identity, and others) until one succeeds. However, this convenience introduces unpredictability: you cannot guarantee which credential in the chain will be used at runtime.

In shared or production environments, this can lead to subtle problems. For example, if a developer runs az login on a VM that normally authenticates via managed identity, DefaultAzureCredential may silently fall back to the CLI credential with different permissions. Microsoft recommends using a deterministic credential (such as ManagedIdentityCredential) in production instead of relying on the automatic chain.

For Cosmos Shell usage:

  • Local development: DefaultAzureCredential (endpoint-only connection) is a good default. It picks up your Azure CLI or VS Code session automatically.
  • CI/CD pipelines: Prefer explicit credential types — --managed-identity for Azure-hosted runners, or COSMOSDB_SHELL_TOKEN with a pre-obtained token.
  • Shared VMs or containers: Use --managed-identity or --tenant to avoid resolving to an unintended identity.

Environment Variables

Both COSMOSDB_SHELL_ACCOUNT_KEY and COSMOSDB_SHELL_TOKEN pass credentials through environment variables. Be aware of the following:

  • Environment variable values may be visible to other processes on the same system (e.g., via /proc on Linux or ps eww on macOS).
  • Values may persist in shell history if set inline (e.g., export COSMOSDB_SHELL_ACCOUNT_KEY=... in .bash_history).
  • In CI/CD systems, use masked secret variables (Azure Pipelines secrets, GitHub Actions secrets) to prevent credentials from appearing in build logs.
  • Avoid setting credential environment variables in shared or multi-user environments.

MCP Considerations

When running with --mcp, the MCP server inherits the shell's connection credentials. It cannot restrict access below what the underlying connection provides.

  • If the shell is connected with an account key, every MCP client action has full, unrestricted account access — there is no RBAC layer to limit operations.
  • If the shell is connected with Entra ID, access is governed by the RBAC roles assigned to the authenticated identity, enabling least-privilege scoping.
  • The MCP client may relay command outputs and query results to a remote LLM. Treat all data returned through MCP as potentially shared with an external service.

Prefer Entra ID authentication with least-privilege RBAC roles when using MCP, especially if the MCP client connects to a third-party AI service. See MCP Security for the full MCP security checklist.