Merge pull request #263654 from niklarin/aad5

Managed identities for Azure Cosmos DB for PostgreSQL

Author: prmerger-automator[bot]

articles/cosmos-db/postgresql/concepts-authentication.md

@@ -6,21 +6,13 @@ ms.author: nlarin
 ms.service: cosmos-db
 ms.subservice: postgresql
 ms.topic: conceptual
-ms.date: 11/07/2023
+ms.date: 02/06/2024
 ---
 
 # Microsoft Entra ID and PostgreSQL authentication with Azure Cosmos DB for PostgreSQL
 
 [!INCLUDE [PostgreSQL](../includes/appliesto-postgresql.md)]
 
-> [!IMPORTANT]
-> Microsoft Entra ID (formerly Azure Active Directory) authentication in Azure Cosmos DB for PostgreSQL is currently in preview.
-> This preview version is provided without a service level agreement, and it's not recommended
-> for production workloads. Certain features might not be supported or might have constrained 
-> capabilities.
->
-> You can see a complete list of other new features in [preview features](product-updates.md#features-in-preview).
-
 Azure Cosmos DB for PostgreSQL supports PostgreSQL authentication and integration with Microsoft Entra ID. Each Azure Cosmos DB for PostgreSQL cluster is created with native PostgreSQL authentication enabled and one built-in PostgreSQL role named `citus`. You can add more native PostgreSQL roles after cluster provisioning is completed.
 
 You can also enable Microsoft Entra ID (formerly Azure Active Directory) authentication on a cluster in addition to the PostgreSQL authentication method or instead of it. You can configure authentication methods on each Azure Cosmos DB for PostgreSQL cluster independently. If you need to change authentication method, you can do it at any time after cluster provisioning is completed. Changing authentication methods doesn't require cluster restart.
@@ -62,8 +54,9 @@ Notably, the `citus` role has some restrictions:
 `citus` role can't be deleted but would be disabled if 'Microsoft Entra ID authentication only' authentication method is selected on cluster.
 
 <a name='azure-active-directory-authentication-preview'></a>
+<a name='microsoft-entra-id-authentication-preview'></a>
 
-## Microsoft Entra ID authentication (preview)
+## Microsoft Entra ID authentication
 
 [Microsoft Entra ID](/entra/fundamentals/whatis) (formerly Azure Active Directory) authentication is a mechanism of connecting to Azure Cosmos DB  for PostgreSQL using identities defined in Microsoft Entra ID. With Microsoft Entra ID authentication, you can manage database user identities and other Microsoft services in a central location, which simplifies permission management.
 
@@ -79,9 +72,9 @@ Benefits of using Microsoft Entra ID include:
 
 ### Manage PostgreSQL access for Microsoft Entra ID principals
 
-When Microsoft Entra ID authentication is enabled and Microsoft Entra ID principal is added as a Microsoft Entra ID administrator, the account gets the same privileges as [the `citus` role](#the-citus-role). The Microsoft Entra ID administrator sign-in can be a Microsoft Entra ID user, Service Principal or Managed Identity. Multiple Microsoft Entra ID administrators can be configured at any time and you can optionally disable PostgreSQL (password) authentication to the Azure Cosmos DB for PostgreSQL cluster for better auditing and compliance needs.
+When Microsoft Entra ID authentication is enabled and Microsoft Entra ID principal is added as a Microsoft Entra ID administrator, the account gets the same privileges as [the `citus` role](#the-citus-role). The Microsoft Entra ID administrator sign-in can be a Microsoft Entra ID user, Service Principal, or Managed Identity. Multiple Microsoft Entra ID administrators can be configured at any time and you can optionally disable PostgreSQL (password) authentication to the Azure Cosmos DB for PostgreSQL cluster for better auditing and compliance needs.
 
-Additionally, any number of non-admin Microsoft Entra ID roles can be added to a cluster at any time once Microsoft Entra ID authentication is enabled. Database permissions for non-admin Microsoft Entra ID roles are managed similar to regular roles.
+Additionally, any number of nonadmin Microsoft Entra ID roles can be added to a cluster at any time once Microsoft Entra ID authentication is enabled. Database permissions for nonadmin Microsoft Entra ID roles are managed similar to regular roles.
 
 <a name='connect-using-azure-ad-identities'></a>
 
@@ -109,7 +102,7 @@ Once you've authenticated against the Microsoft Entra ID, you then retrieve a to
 
 ## Next steps
 
-- Check out [Microsoft Entra ID limits and limitations in Azure Cosmos DB for PostgreSQL](./reference-limits.md#azure-active-directory-authentication)
+- Check out [Microsoft Entra ID limits and limitations in Azure Cosmos DB for PostgreSQL](./reference-limits.md#microsoft-entra-id-authentication)
 - [Learn how to configure authentication for Azure Cosmos DB for PostgreSQL clusters](./how-to-configure-authentication.md)
 - Set up private network access to the cluster nodes, see [Manage private access](./howto-private-access.md)
 - Set up public network access to the cluster nodes, see [Manage public access](./howto-manage-firewall-using-portal.md)

articles/cosmos-db/postgresql/how-to-configure-authentication.md

@@ -6,21 +6,13 @@ ms.author: nlarin
 ms.service: cosmos-db
 ms.subservice: postgresql
 ms.topic: how-to
-ms.date: 11/06/2023
+ms.date: 02/06/2024
 ---
 
 # Use Microsoft Entra ID and native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL
 
 [!INCLUDE [PostgreSQL](../includes/appliesto-postgresql.md)]
 
-> [!IMPORTANT]
-> Microsoft Entra ID (formerly Azure Active Directory) authentication in Azure Cosmos DB for PostgreSQL is currently in preview.
-> This preview version is provided without a service level agreement, and it's not recommended
-> for production workloads. Certain features might not be supported or might have constrained
-> capabilities.
->
-> You can see a complete list of other new features in [preview features](product-updates.md#features-in-preview).
-
 In this article, you configure authentication methods for Azure Cosmos DB for PostgreSQL. You manage Microsoft Entra ID admin users and native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL. You also learn how to use a Microsoft Entra ID token with Azure Cosmos DB for PostgreSQL.
 
 An Azure Cosmos DB for PostgreSQL cluster is created with one built-in native PostgreSQL role named 'citus'. You can add more native PostgreSQL roles after cluster provisioning is completed.
@@ -33,9 +25,9 @@ You need to use Azure portal to configure authentication methods on an Azure Cos
 Complete the following items on your Azure Cosmos DB for PostgreSQL cluster to enable or disable Microsoft Entra ID authentication and native PostgreSQL authentication.
 
 1. On the cluster page, under the **Cluster management** heading, choose **Authentication** to open authentication management options.
-1. In **Authentication methods** section, choose **PostgreSQL authentication only**, **Microsoft Entra ID authentication (preview)**, or **PostgreSQL and Microsoft Entra ID authentication (preview)** as the authentication method based on your requirements.
+1. In **Authentication methods** section, choose **PostgreSQL authentication only**, **Microsoft Entra ID authentication**, or **PostgreSQL and Microsoft Entra ID authentication** as the authentication method based on your requirements.
 
-Once done proceed with [configuring Microsoft Entra ID authentication](#configure-azure-active-directory-authentication) or [adding native PostgreSQL roles](#configure-native-postgresql-authentication) on **Authentication** page.
+Once done proceed with [configuring Microsoft Entra ID authentication](#configure-azure-active-directory-authentication) or [adding native PostgreSQL roles](#configure-native-postgresql-authentication) on the same **Authentication** page.
 
 <a name='configure-azure-active-directory-authentication'></a>
 
@@ -54,7 +46,7 @@ Users need to be allowed to sign in to Azure Cosmos DB for PostgreSQL in the Mic
 1. Open 'Microsoft Entra ID' service.
 1. On the **Overview** page of Microsoft Entra ID service in the **Overview** section, search for 'b4fa09d8-5da5-4352-83d9-05c2a44cf431' application ID.
 1. Choose 'Azure Cosmos DB for PostgreSQL AAD Authentication' enterprise application in the search results.
-1. In the Azure Cosmos DB for PostgreSQL AAD Authentication enterprise application, choose **Properties** page.
+1. In the **Azure Cosmos DB for PostgreSQL AAD Authentication** enterprise application, choose **Properties** page.
 1. Set **Enabled for users to sign-in?** to **Yes** and save the change.
 
 # [Azure CLI](#tab/cli)
@@ -64,11 +56,14 @@ az ad sp update --id b4fa09d8-5da5-4352-83d9-05c2a44cf431 --set accountEnabled=t
 ```
 ---
 
+> [!NOTE]
+> Editing enterprise application's properties such as 'Enabled for users to sign-in' requires permissions granted to the Global Administrator, Cloud Application Administrator, or Application Administrator roles. See [the list of built-in Microsoft Entra roles](/entra/identity/role-based-access-control/permissions-reference).
+
 ### Add Microsoft Entra ID admins to Azure Cosmos DB for PostgreSQL cluster
 
 To add or remove Microsoft Entra ID roles on cluster, follow these steps on **Authentication** page:
 
-1. In **Microsoft Entra ID authentication (preview)** section, select **Add Microsoft Entra ID admins**.
+1. In **Microsoft Entra ID authentication** section, select **Add Microsoft Entra ID admins**.
 1. In **Select Microsoft Entra ID Admins** panel, select one or more valid Microsoft Entra ID user or enterprise application in the current AD tenant to be a Microsoft Entra ID administrator on your Azure Cosmos DB for PostgreSQL cluster.
 1. Use **Select** to confirm your choice.
 1. In the **Authentication** page, select **Save** in the toolbar to save changes or proceed with adding native PostgreSQL roles.
@@ -107,14 +102,16 @@ az login
 
 The command opens a browser window to the Microsoft Entra ID authentication page. It requires you to give your Microsoft Entra ID user name and password.
 
+The user account name you use to authenticate (for example, [email protected]) is the one the access token will be generated for in the next step.
+
 <a name='retrieve-the-azure-ad-access-token'></a>
 
 ### Retrieve the Microsoft Entra ID access token
 
 Use the Azure CLI to acquire an access token for the Microsoft Entra ID authenticated user to access Azure Cosmos for PostgreSQL. Here's an example:
 
 ```azurecli-interactive
-az account get-access-token --resource https://postgres.cosmos.azure.com
+az account get-access-token --resource https://token.postgres.cosmos.azure.com
 ```
 
 After authentication is successful, Microsoft Entra ID returns an access token for current Azure subscription:
@@ -129,7 +126,7 @@ After authentication is successful, Microsoft Entra ID returns an access token f
 }
 ```
 
-The TOKEN is a Base64 string. It encodes all the information about the authenticated user and is targeted to the Azure Cosmos DB for PostgreSQL service. The token is valid for at least 5 minutes with the maximum of 90 minutes. The expiresOn defines actual token expiration time.
+The TOKEN is a Base64 string. It encodes all the information about the authenticated user and is associated with the Azure Cosmos DB for PostgreSQL service. The token is valid for at least 5 minutes with the maximum of 90 minutes. The **expiresOn** defines actual token expiration time.
 
 ### Use a token as a password for signing in with client psql
 
@@ -167,7 +164,7 @@ export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --quer
 > or clear the PGPASSWORD variable value to enter the password interactively.
 > Authentication would fail with the wrong value in PGPASSWORD.
 
-Now you can initiate a connection with Azure Cosmos DB for PostgreSQL as you usually would (without 'password' parameter in the command line):
+Now you can initiate a connection with Azure Cosmos DB for PostgreSQL using the Microsoft Entra ID user account that the access token was generated for. You would do it as you usually would with the user account as the user and without 'password' parameter in the command line:
 
 ```sql
 psql "host=mycluster.[uniqueID].postgres.cosmos.azure.com [email protected] dbname=[db_name] sslmode=require"