Introduction to Azure Cosmos DB Keys
Azure Cosmos DB is a globally distributed, multi-model database service that enables you to rapidly develop and scale high-performance applications. Access control is a critical aspect of securing your database. Cosmos DB uses access keys to authenticate and authorize operations against your database accounts.
There are two primary types of keys associated with Azure Cosmos DB accounts:
- Primary and Secondary Keys: These are account-level keys used for full administrative access to the Cosmos DB account.
- Resource Tokens: These are user-defined, fine-grained access tokens that grant permissions to specific resources (databases, collections, documents) within a Cosmos DB account.
Account Keys (Primary & Secondary)
Account keys provide complete control over your Cosmos DB account. They are ideal for administrative tasks, but should be handled with extreme care due to their powerful nature.
Types of Account Keys:
- Primary Key: The first master key generated for your account.
- Secondary Key: A backup master key. If the primary key is compromised or needs to be rotated, you can use the secondary key.
- Primary Read-Only Key: A read-only version of the primary key.
- Secondary Read-Only Key: A read-only version of the secondary key.
These keys are typically used by applications to authenticate when performing CRUD operations, managing collections, and accessing other account-level features.
Where to Find Your Account Keys:
- Navigate to your Azure Cosmos DB account in the Azure portal.
- In the left-hand navigation menu, under "Settings", select "Keys".
- You will see your Primary Key, Secondary Key, Primary Read-Only Key, and Secondary Read-Only Key listed.
Note: It is a security best practice to rotate your keys regularly and avoid embedding them directly in application code. Consider using Azure Key Vault for secure storage and retrieval of your connection strings and keys.
Resource Tokens
Resource tokens offer a more granular approach to authorization, allowing you to grant specific permissions to users or applications for particular resources. This is especially useful for scenarios where you want to provide limited access to certain data without exposing account-level keys.
How Resource Tokens Work:
- Resource tokens are generated for a specific user and resource(s).
- They grant permissions like read, write, or delete to the designated resources.
- These tokens have a limited lifespan and can be configured with an expiration time.
- They are typically managed by a backend service that authenticates users and then requests resource tokens from the Cosmos DB account on their behalf.
Resource tokens are a key component of the Cosmos DB authorization model for client-side applications.
Key Management Best Practices
Secure Storage
Never hardcode keys in your application code. Utilize services like Azure Key Vault to store and manage your sensitive credentials securely.
Key Rotation
Regularly rotate your primary and secondary account keys to mitigate the risk of compromised credentials.
Principle of Least Privilege
When possible, use resource tokens to grant only the necessary permissions for specific users or applications, rather than relying solely on account keys.
Use Read-Only Keys
For operations that only require reading data, use the read-only keys instead of the primary/secondary keys to enhance security.