Merge pull request #415 from MicrosoftDocs/main

Publish to live, Tuesday 4 AM PST, 10/1

articles/cosmos-db/how-to-configure-integrated-cache.md

@@ -5,7 +5,7 @@ author: jcocchi
 ms.service: azure-cosmos-db
 ms.subservice: nosql
 ms.topic: conceptual
-ms.date: 08/29/2022
+ms.date: 09/30/2024
 ms.author: jucocchi
 ---
 
@@ -61,9 +61,6 @@ When you create a dedicated gateway, an integrated cache is automatically provis
 
 You must ensure the request consistency is session or eventual. If not, the request will always bypass the integrated cache. The easiest way to configure a specific consistency for all read operations is to [set it at the account-level](consistency-levels.md#configure-the-default-consistency-level). You can also configure consistency at the [request-level](how-to-manage-consistency.md#override-the-default-consistency-level), which is recommended if you only want a subset of your reads to utilize the integrated cache.
 
-> [!NOTE]
-> If you are using the Python SDK, you **must** explicitly set the consistency level for each request. The default account-level setting will not automatically apply.
-
 ## Adjust MaxIntegratedCacheStaleness
 
 Configure `MaxIntegratedCacheStaleness`, which is the maximum time in which you're willing to tolerate stale cached data. It's recommended to set the `MaxIntegratedCacheStaleness` as high as possible because it will increase the likelihood that repeated point reads and queries can be cache hits. If you set `MaxIntegratedCacheStaleness` to 0, your read request will **never** use the integrated cache, regardless of the consistency level. When not configured, the default `MaxIntegratedCacheStaleness` is 5 minutes.
@@ -141,7 +138,7 @@ Bypassing the cache is supported in these versions of each SDK:
 | --- | ------------------ |
 | **.NET SDK v3** | *>= 3.39.0* |
 | **Java SDK v4** | *>= 4.49.0* |
-| **Node.js SDK** | Not supported |
+| **Node.js SDK** | *>= 4.1.0* |
 | **Python SDK**  | Not supported |
 
 ### [.NET](#tab/dotnet)
@@ -171,7 +168,16 @@ CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
 
 ### [Node.js](#tab/nodejs)
 
-The bypass integrated cache request option isn't available in the Node.js SDK.
+```javascript
+    const queryRequestOptions = {
+      bypassIntegratedCache: true };
+    const querySpec = {
+      query: "SELECT * from c"
+    };
+    const { resources: items, requestCharge: queryCharge } = await container.items
+      .query(querySpec, queryRequestOptions)
+      .fetchAll();
+```
 
 ### [Python](#tab/python)
 

articles/cosmos-db/includes/get-signed-in-identity.md

@@ -1,7 +1,7 @@
 ---
 ms.service: azure-cosmos-db
 ms.topic: include
-ms.date: 09/24/2024
+ms.date: 10/01/2024
 ms.custom: subject-msia
 zone_pivot_groups: azure-interface-portal-cli-powershell
 ---

articles/cosmos-db/includes/managed-identities.md

@@ -1,7 +1,7 @@
 ---
 ms.service: azure-cosmos-db
 ms.topic: include
-ms.date: 09/24/2024
+ms.date: 10/01/2024
 ms.custom: subject-msia
 zone_pivot_groups: azure-interface-portal-cli-powershell-bicep
 ---

articles/cosmos-db/includes/security-glossary.md

@@ -1,7 +1,7 @@
 ---
 ms.service: azure-cosmos-db
 ms.topic: include
-ms.date: 09/24/2024
+ms.date: 10/01/2024
 ms.custom: subject-msia
 ---
 
@@ -90,18 +90,6 @@ A role assignment grants an identity access to a specific Azure resource. Role a
 
 For more information, see [role assignment concepts](/azure/role-based-access-control/role-assignments).
 
-## Scope
-
-When you assign a role, you must decide what Azure resources or groups to grant access to. The scope of a role assignment defines the level at which an assignment is made.
-
-For example:
-
-- A single resource scope applies permissions to just that singular resource
-- A scope set at the resource group level applies the permissions to all relevant resources within the group
-- Scopes at the management group or subscription levels apply to all child groups and resources
-
-For more information, see [scope overview](/azure/role-based-access-control/scope-overview).
-
 ## Actions
 
 Actions define what specific permissions a [role](#role) has for a target resource. Actions are strings that typically include the resource type and a descriptive name detailing what permissions the action grants. Here are a few common examples:
@@ -187,3 +175,27 @@ Each modern Azure SDK library supports a constructor for their respective client
 ## Unique identifier
 
 Each [identity](#identityprincipal) in Microsoft Entra has a unique identifier. You sometimes see this unique identifier referred to as the `id`, `objectId`, or `principalId`. When creating [role assignments](#role-assignment), you need the unique identifier for the identity that you with to use with the assignment.
+
+## Scope
+
+When you assign a role, you must decide what Azure resources or groups to grant access to. The scope of a role assignment defines the level at which an assignment is made.
+
+For example:
+
+- A single resource scope applies permissions to just that singular resource
+- A scope set at the resource group level applies the permissions to all relevant resources within the group
+- Scopes at the management group or subscription levels apply to all child groups and resources
+
+When you assign a role in Azure role-based access control, it's ideal to set the scope of that assignment to include as little resources as required for your workload. For example, you can set the scope of an assignment to a resource group. That resource group scope includes all Azure Cosmos DB resources within the resource group:
+
+```output
+/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>
+```
+
+Alternatively, you can set the scope to a single Azure resource and make your assignment of permissions more granular and narrow. In this example, the provider and name of the Azure Cosmos DB resource are used to narrow the scope:
+
+```output
+/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>
+```
+
+For more information, see [Azure role-based access control scope](/azure/role-based-access-control/scope-overview).

articles/cosmos-db/includes/validate-control-plane-role-based-access.md

@@ -0,0 +1,119 @@
+---
+ms.service: azure-cosmos-db
+ms.topic: include
+ms.date: 10/01/2024
+zone_pivot_groups: azure-interface-portal-cli-powershell-bicep
+---
+
+## Validate control plane access in code
+
+Finally, validate that you correctly granted access using application code and the Azure Management SDK in your preferred programming language.
+
+### [C#](#tab/csharp)
+
+```csharp
+using Azure.Identity;
+using Azure.ResourceManager;
+
+DefaultAzureCredential credential = new();
+
+ArmClient client = new(credential);
+```
+
+> [!IMPORTANT]
+> This code sample uses the [`Azure.ResourceManager.CosmosDB`](https://www.nuget.org/packages/Azure.ResourceManager.CosmosDB) and [`Azure.Identity`](https://www.nuget.org/packages/Azure.Identity) libraries from NuGet.
+
+### [JavaScript](#tab/javascript)
+
+```javascript
+const { CosmosDBManagementClient } = require('@azure/arm-cosmosdb');
+const { DefaultAzureCredential } = require('@azure/identity');
+
+const subscriptionId = "<subscription-id>";
+
+const credential = new DefaultAzureCredential();
+
+const client = new CosmosDBManagementClient(credential, subscriptionId);
+```
+
+> [!IMPORTANT]
+> This code sample uses the [`@azure/arm-cosmosdb`](https://www.npmjs.com/package/@azure/arm-cosmosdb) and [`@azure/identity`](https://www.npmjs.com/package/@azure/identity) libraries from npm.
+
+### [TypeScript](#tab/typescript)
+
+```typescript
+import { CosmosDBManagementClient } from '@azure/arm-cosmosdb';
+import { TokenCredential, DefaultAzureCredential } from '@azure/identity';
+
+let subscriptionId: string = "<subscription-id>";
+
+let credential: TokenCredential = new DefaultAzureCredential();
+
+const client: CosmosDBManagementClient = new CosmosDBManagementClient(credential, subscriptionId);
+```
+
+> [!IMPORTANT]
+> This code sample uses the [`@azure/arm-cosmosdb`](https://www.npmjs.com/package/@azure/arm-cosmosdb) and [`@azure/identity`](https://www.npmjs.com/package/@azure/identity) libraries from npm.
+
+### [Python](#tab/python)
+
+```python
+from azure.mgmt.cosmosdb import CosmosDBManagementClient
+from azure.identity import DefaultAzureCredential
+
+subscription_id = "<subscription-id>"
+
+credential = DefaultAzureCredential()
+
+client = CosmosDBManagementClient(credential=credential, subscription=subscription_id)
+```
+
+> [!IMPORTANT]
+> This code sample uses the [`azure-mgmt-cosmosdb`](https://pypi.org/project/azure-mgmt-cosmosdb/) and [`azure-identity`](https://pypi.org/project/azure-identity/) libraries from PyPI.
+
+### [Go](#tab/go)
+
+```go
+package main
+
+import (
+    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
+    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos"
+)
+
+const subscriptionId = "<subscription-id>"
+
+func main() {
+    credential, _ := azidentity.NewDefaultAzureCredential(nil)
+
+    client, _ := armcosmos.NewDatabaseClient(subscriptionId, credential, nil)
+}
+```
+
+> [!IMPORTANT]
+> This code sample uses the [`azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos`](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos) and [`azure/azure-sdk-for-go/sdk/azidentity`](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity) libraries from Go.
+
+### [Java](#tab/java)
+
+```java
+package com.example;
+
+import com.azure.core.management.profile.AzureProfile;
+import com.azure.core.management.AzureEnvironment;
+import com.azure.identity.DefaultAzureCredential;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+import com.azure.resourcemanager.cosmos.CosmosManager;
+
+public class CosmosDB {
+    public static void main(String[] args) {
+        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
+        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
+          .build();
+
+        CosmosManager manager = CosmosManager.authenticate(credential, profile);
+    }
+}
+```
+
+> [!IMPORTANT]
+> This code sample uses the [`com.azure.resourcemanager/azure-resourcemanager-cosmos`](https://mvnrepository.com/artifact/com.azure.resourcemanager/azure-resourcemanager-cosmos) and [`com.azure/azure-identity`](https://mvnrepository.com/artifact/com.azure/azure-identity) libraries from Maven.

articles/cosmos-db/nosql/TOC.yml

@@ -437,27 +437,13 @@
       items:
         - name: Security overview
           href: ../database-security.md
-        - name: Role-based access control
+        - name: Role-based access control guide
           displayName: RBAC, Entra
-          expanded: true
-          items:
-            - name: Security glossary
-              href: security/glossary.md
-            - name: Get signed-in identity
-              href: security/how-to-get-signed-in-identity.md
-            - name: Create managed identities
-              displayName: principals
-              href: security/how-to-create-managed-identities.md
-        - name: Secure access to data
-          displayName: primary key, resource token, users, roles
-          href: ../secure-access-to-data.md
+          href: security/index.md
         - name: Data encryption
           href: ../database-encryption-at-rest.md
         - name: Service tags
           href: /azure/virtual-network/service-tags-overview?toc=/azure/cosmos-db/toc.json&bc=/azure/cosmos-db/breadcrumb/toc.json
-        - name: Azure role-based access control
-          displayName: rbac
-          href: ../role-based-access-control.md
         - name: Azure Policy support
           href: ../policy.md
         - name: Security controls by Azure Policy
@@ -929,19 +915,13 @@
               href: ../troubleshoot-cmk.md
             - name: Access Azure Key Vault with managed identity
               href: ../access-key-vault-managed-identity.md
-        - name: Use managed identities with Azure services
-          href: ../how-to-setup-managed-identity.md
-        - name: Use managed identities to access data
-          href: ../managed-identity-based-authentication.yml
-        - name: Migrate to passwordless authentication
-          href: migrate-passwordless.md
-          displayName: msi, managed service identity, aad, azure active directory, identity
-        - name: Role-based access control
-          items:
-            - name: Configure role-based access control to data
-              href: ../how-to-setup-rbac.md
-            - name: Restrict user access to data operations only
-              href: ../how-to-restrict-user-data.md
+        - name: Disable key-based authentication
+          displayName: key, ropc, connection string
+          href: security/how-to-disable-key-based-authentication.md?context=/azure/cosmos-db/context/context
+        - name: Grant role-based access control access for resources
+          href: security/how-to-grant-control-plane-role-based-access.md?context=/azure/cosmos-db/context/context
+        - name: Grant role-based access control access for data
+          href: security/how-to-grant-data-plane-role-based-access.md?context=/azure/cosmos-db/context/context
         - name: Configure Cross Origin Resource Sharing (CORS)
           href: how-to-configure-cross-origin-resource-sharing.md
         - name: Use Azure Key Vault to store keys

articles/cosmos-db/nosql/faq.yml

@@ -8,7 +8,7 @@ metadata:
   ms.service: azure-cosmos-db
   ms.subservice: nosql
   ms.topic: faq
-  ms.date: 09/24/2024
+  ms.date: 10/01/2024
 title: Frequently asked questions about Azure Cosmos DB for NoSQL
 summary: |
   [!INCLUDE[NoSQL](../includes/appliesto-nosql.md)]
@@ -124,11 +124,31 @@ sections:
       - question: |
           What is role-based access control (RBAC)?
         answer: |
-          Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within an enterprise. In Azure Cosmos DB, RBAC is used to grant data-plane access to users and applications.
+          Role-based access control (RBAC) is a method of regulating access to computer or network resources based on the roles of individual users within an enterprise. In Azure Cosmos DB, RBAC is used to grant data-plane access to users and applications. For more information about various terms in role-based access control, see the [security glossary](security/glossary.md).
       - question: |
           How do I enable data-plane role-based access control for Azure Cosmos DB for NoSQL?
         answer: |
-          Use the Azure Cosmos DB native role-based access control (RBAC) feature to grant data-plane access to users and applications.
+          Use the Azure Cosmos DB native role-based access control (RBAC) feature to grant data-plane access to users and applications. For more information, see [Grant data-plane role-based access](security/how-to-grant-data-plane-role-based-access.md).  
+      - question: |
+          Which Azure Cosmos DB APIs support data-plane role-based access control?
+        answer: |
+          As of now, only the NoSQL API is supported.
+      - question: |
+          Is it possible to manage role definitions and role assignments from the Azure portal?
+        answer: |
+          Azure portal support for role management isn't available yet.
+      - question: |
+          Which SDKs in Azure Cosmos DB API for NoSQL support role-based access control?
+        answer: |
+          The .NET V3, Java V4, JavaScript V3, and Python V4.3+ SDKs are currently supported.
+      - question: |
+          Is the Microsoft Entra token automatically refreshed by the Azure Cosmos DB SDKs when it expires?
+        answer: |
+          Yes.
+      - question: |
+          Is it possible to disable the usage of the account primary/secondary keys when using role-based access control?
+        answer: |
+          Yes. For more information, see [disable key-based authentication](security/how-to-disable-key-based-authentication.md).
 additionalContent: |
   ## Related content