Azure Databases built-in role

Cosmos DB Account Reader Role

Reads Azure Cosmos DB account and resource metadata and can retrieve read-only account keys. It has no Azure RBAC DataActions, so it does not provide Microsoft Entra-authorized item access; the read-only keys are a separate key-based credential path and must be treated as sensitive.

Control-plane actions (7)

• Microsoft.Authorization/*/read
• Microsoft.DocumentDB/*/read
• Microsoft.DocumentDB/databaseAccounts/readonlykeys/action
• Microsoft.Insights/MetricDefinitions/read
• Microsoft.Insights/Metrics/read
• Microsoft.Resources/subscriptions/resourceGroups/read
• Microsoft.Support/*

Data-plane actions (0)

None — this role grants no data-plane (data access) actions.

Excluded actions (0)

None

Assignable scopes (1)

• /

Practical scope

Assign on an individual Azure Cosmos DB account when the principal needs account visibility or its read-only keys. A resource-group or parent assignment is inherited by every contained account. Native Azure Cosmos DB data-plane roles use account-internal scopes and are assigned separately.

Common use cases (2)

• Inspect Azure Cosmos DB account configuration, resource metadata, health, and metrics without changing the account.
• Retrieve a read-only account key for a documented compatibility workflow that cannot yet use Microsoft Entra data-plane authorization.

Prerequisites (2)

• An Azure Cosmos DB account must already exist, and the access owner must confirm whether read-only key retrieval is genuinely required.
• For Microsoft Entra-authenticated queries or item reads, assign a native Cosmos DB data-plane role such as Cosmos DB Built-in Data Reader separately.

Best practices (3)

• Do not use this role as an ordinary metadata reader when read-only key retrieval is unnecessary; use a narrower custom role where required.
• Prefer Microsoft Entra data-plane authorization and disable key-based authentication for secure workloads after dependent clients are migrated.
• Assign at the individual account and protect any retrieved read-only key as a credential.

Security considerations (3)

• The role cannot modify the account and has no DataActions, but its readonlyKeys action can expose a credential for key-authenticated reads.
• Key-based authentication is separate from native Cosmos DB data-plane RBAC and bypasses identity-specific data-role assignments while the key remains valid.
• A broad parent assignment enables read-only key retrieval for every inherited Cosmos DB account.

Assignment guidance

Assign Cosmos DB Account Reader Role on one account only when account visibility or read-only key retrieval is approved. Use native Cosmos DB data-plane roles for applications, disable local authentication when possible, and use a custom management reader if key retrieval must be excluded.

Related roles (2)

• DocumentDB Account Contributor: The Databases role page directs account-management scenarios to DocumentDB Account Contributor, which is substantially broader and includes account lifecycle operations.
• Cosmos DB Built-in Data Reader: Native Azure Cosmos DB data-plane role for Microsoft Entra-authorized item reads, separate from this Azure management role.

Editorial sources (5)

• Azure built-in roles for Databases →

  Supports: Description, Practical scope, Common use cases, Security considerations, Related roles. Retrieved 2026-07-16.

• Steps to assign an Azure role →

  Supports: Assignment guidance. Retrieved 2026-07-16.

• Understand scope for Azure RBAC →

  Supports: Practical scope, Assignment guidance. Retrieved 2026-07-16.

• Best practices for Azure RBAC →

  Supports: Best practices. Retrieved 2026-07-16.

• Connect to Azure Cosmos DB for NoSQL using role-based access control and Microsoft Entra ID →

  Supports: Description, Practical scope, Common use cases, Prerequisites, Best practices, Security considerations, Assignment guidance, Related roles. Retrieved 2026-07-16.

Official Microsoft Learn documentation →