Skip to content

Commit 1b2c8ac

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #247227 from niklarin/aad2
AAD authentication
2 parents d6e85ca + 77f7373 commit 1b2c8ac

File tree

4 files changed

+340
-3
lines changed

4 files changed

+340
-3
lines changed

‎articles/cosmos-db/postgresql/TOC.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@
9494
- name: Private access
9595
href: concepts-private-access.md
9696
displayName: private, link
97+
- name: Azure AD and Postgres authentication
98+
href: concepts-authentication.md
99+
displayName: Azure Active Directory, AAD, authentication, PostgreSQL roles
97100
- name: Node DNS names
98101
href: concepts-node-domain-name.md
99102
displayName: DNS, FQDN, connection, connect
@@ -157,7 +160,7 @@
157160
href: howto-ingest-azure-data-factory.md
158161
- name: Manage
159162
items:
160-
- name: Create users
163+
- name: Manage users
161164
href: howto-create-users.md
162165
- name: Schedule maintenance
163166
href: howto-maintenance.md
@@ -214,6 +217,9 @@
214217
- name: Manage private access
215218
href: howto-private-access.md
216219
displayName: network, private link
220+
- name: Manage Azure AD and Postgres users
221+
href: how-to-configure-authentication.md
222+
displayName: Azure Active Directory, PosgreSQL roles, authentication
217223
- name: Customer managed keys
218224
href: how-to-customer-managed-keys.md
219225
displayName: customer-managed, keys, cmk

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: Active Directory authentication - Azure Cosmos DB for PostgreSQL
3+
description: Learn about the concepts of native PostgreSQL and Azure Active Directory authentication with Azure Cosmos DB for PostgreSQL
4+
author: niklarin
5+
ms.author: nlarin
6+
ms.service: cosmos-db
7+
ms.subservice: postgresql
8+
ms.topic: conceptual
9+
ms.date: 08/02/2023
10+
---
11+
12+
# Azure Active Directory and PostgreSQL authentication with Azure Cosmos DB for PostgreSQL
13+
14+
[!INCLUDE [PostgreSQL](../includes/appliesto-postgresql.md)]
15+
16+
> [!IMPORTANT]
17+
> Azure Active Directory authentication in Azure Cosmos DB for PostgreSQL is currently in preview.
18+
> This preview version is provided without a service level agreement, and it's not recommended
19+
> for production workloads. Certain features might not be supported or might have constrained
20+
> capabilities.
21+
>
22+
> [Contact us](mailto:[email protected]) if you're interested in participating in Azure Active Directory authentication
23+
> for Azure Cosmos DB for PostgreSQL preview.
24+
>
25+
> You can see a complete list of other new features in [preview features](product-updates.md#features-in-preview).
26+
27+
Azure Cosmos DB for PostgreSQL supports PostgreSQL authentication and integration with Azure Active Directory (Azure AD). 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.
28+
29+
You can also enable Azure AD 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.
30+
31+
## PostgreSQL authentication
32+
33+
The PostgreSQL engine uses
34+
[roles](https://www.postgresql.org/docs/current/sql-createrole.html) to control
35+
access to database objects. A newly created Azure Cosmos DB for PostgreSQL cluster
36+
comes with several roles predefined:
37+
38+
* The [default PostgreSQL roles](https://www.postgresql.org/docs/current/default-roles.html)
39+
* `postgres`
40+
* `citus`
41+
42+
Since Azure Cosmos DB for PostgreSQL is a managed PaaS service, only Microsoft can sign in with the
43+
`postgres` superuser role. For limited administrative access, Azure Cosmos DB for PostgreSQL
44+
provides the `citus` role.
45+
46+
The managed service needs to replicate all PostgreSQL roles to all nodes in a cluster. To facilitate this requirement, all other PostgreSQL roles need to be created using Azure Cosmos DB for PostgreSQL management capabilities.
47+
48+
### The Citus role
49+
50+
Permissions for the `citus` role:
51+
52+
* Read all configuration variables, even variables normally visible only to
53+
superusers.
54+
* Read all pg\_stat\_\* views and use various statistics-related
55+
extensions--even views or extensions normally visible only to superusers.
56+
* Execute monitoring functions that may take ACCESS SHARE locks on tables,
57+
potentially for a long time.
58+
* [Create PostgreSQL extensions](reference-extensions.md).
59+
60+
Notably, the `citus` role has some restrictions:
61+
62+
* Can't create roles
63+
* Can't create databases
64+
65+
`citus` role can't be deleted but would be disabled if 'Azure Active Directory authentication only' authentication method is selected on cluster.
66+
67+
## Azure Active Directory authentication (preview)
68+
69+
[Microsoft Azure Active Directory (Azure AD)](./../../active-directory/fundamentals/active-directory-whatis.md) authentication is a mechanism of connecting to Azure Cosmos DB for PostgreSQL using identities defined in Azure AD. With Azure AD authentication, you can manage database user identities and other Microsoft services in a central location, which simplifies permission management.
70+
71+
Benefits of using Azure AD include:
72+
73+
- Authentication of users across Azure Services in a uniform way
74+
- Management of password policies and password rotation in a single place
75+
- Multiple forms of authentication supported by Azure Active Directory, which can eliminate the need to store passwords
76+
- Azure AD authentication uses PostgreSQL database roles to authenticate identities at the database level
77+
- Support of token-based authentication for applications connecting to Azure Cosmos DB for PostgreSQL
78+
79+
### Manage PostgreSQL access for Azure AD principals
80+
81+
When Azure AD authentication is enabled and Azure AD principal is added as an Azure AD administrator, the account gets the same privileges as [the `citus` role](#the-citus-role). The Azure AD administrator sign-in can be an Azure AD user, Service Principal or Managed Identity. Multiple Azure AD 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.
82+
83+
Additionally, any number of non-admin Azure AD roles can be added to a cluster at any time once Azure AD authentication is enabled. Database permissions for non-admin Azure AD roles are managed similar to regular roles.
84+
85+
### Connect using Azure AD identities
86+
87+
Azure Active Directory authentication supports the following methods of connecting to a database using Azure AD identities:
88+
89+
- Azure Active Directory Password
90+
- Azure Active Directory Integrated
91+
- Azure Active Directory Universal with MFA
92+
- Using Active Directory Application certificates or client secrets
93+
- Managed Identity
94+
95+
Once you've authenticated against the Active Directory, you then retrieve a token. This token is your password for logging in.
96+
97+
### Other considerations
98+
99+
- Multiple Azure AD principals (a user, service principal, or managed identity) can be configured as Azure AD administrator for an Azure Cosmos DB for PostgreSQL cluster at any time.
100+
- If an Azure AD principal is deleted from Azure AD service, it still remains as a PostgreSQL role on the cluster, but it's no longer able to acquire new access token. In this case, although the matching role still exists in the Postgres database it's unable to authenticate to the cluster nodes. Database administrators need to transfer ownership and drop such roles manually.
101+
102+
> [!NOTE]
103+
> Login with the deleted Azure AD user can still be done till the token expires (up to 90 minutes from token issuing). If you also remove the user from Azure Cosmos DB for PostgreSQL cluster this access will be revoked immediately.
104+
105+
- Azure Cosmos DB for PostgreSQL matches access tokens to the database role using the user’s unique Azure Active Directory user ID, as opposed to using the username. If an Azure AD user is deleted and a new user is created with the same name, Azure Cosmos DB for PostgreSQL considers that a different user. Therefore, if a user is deleted from Azure AD and a new user is added with the same name the new user would be unable to connect with the existing role.
106+
107+
## Next steps
108+
109+
- To learn how to configure authentication for Azure Cosmos DB for PostgreSQL clusters, see [Use Azure Active Directory and native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL](./how-to-configure-authentication.md).
110+
- To set up private network access to the cluster nodes, see [Manage private access](./howto-private-access.md).
111+
- To 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‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
---
2+
title: Use Azure Active Directory and native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL
3+
description: Learn how to set up Azure Active Directory (Azure AD) and add native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL.
4+
author: niklarin
5+
ms.author: nlarin
6+
ms.service: cosmos-db
7+
ms.subservice: postgresql
8+
ms.topic: how-to
9+
ms.date: 08/01/2023
10+
---
11+
12+
# Use Azure Active Directory and native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL
13+
14+
[!INCLUDE [PostgreSQL](../includes/appliesto-postgresql.md)]
15+
16+
> [!IMPORTANT]
17+
> Azure Active Directory authentication in Azure Cosmos DB for PostgreSQL is currently in preview.
18+
> This preview version is provided without a service level agreement, and it's not recommended
19+
> for production workloads. Certain features might not be supported or might have constrained
20+
> capabilities.
21+
>
22+
> [Contact us](mailto:[email protected]) if you're interested in participating in Azure Active Directory authentication
23+
> for Azure Cosmos DB for PostgreSQL preview.
24+
>
25+
> You can see a complete list of other new features in [preview features](product-updates.md#features-in-preview).
26+
27+
In this article, you configure authentication methods for Azure Cosmos DB for PostgreSQL. You manage Azure Active Directory (Azure AD) admin users and native PostgreSQL roles for authentication with Azure Cosmos DB for PostgreSQL. You also learn how to use an Azure AD token with Azure Cosmos DB for PostgreSQL.
28+
29+
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.
30+
31+
You can also configure Azure AD authentication for Azure Cosmos DB for PostgreSQL. You can enable Azure AD authentication in addition or instead of the native PostgreSQL authentication on your cluster. You can change authentication methods enabled on cluster at any point after the cluster is provisioned. When Azure Active Directory authentication is enabled, you can add multiple Azure AD users to an Azure Cosmos DB for PostgreSQL cluster and make any of them administrators. Azure AD user can be a user or a service principal.
32+
33+
## Choose authentication method
34+
You need to use Azure portal to configure authentication methods on an Azure Cosmos DB for PostgreSQL cluster.
35+
36+
Complete the following items on your Azure Cosmos DB for PostgreSQL cluster to enable or disable Azure Active Directory authentication and native PostgreSQL authentication.
37+
38+
1. On the cluster page, under the **Cluster management** heading, choose **Authentication** to open authentication management options.
39+
1. In **Authentication methods** section, choose **PostgreSQL authentication only**, **Azure Active Directory authentication (preview)**, or **PostgreSQL and Azure Active Directory authentication (preview)** as the authentication method based on your requirements.
40+
41+
Once done proceed with [configuring Azure Active Directory authentication](#configure-azure-active-directory-authentication) or [adding native PostgreSQL roles](#configure-native-postgresql-authentication) on **Authentication** page.
42+
43+
## Configure Azure Active Directory authentication
44+
45+
To add or remove Azure AD roles on cluster, follow these steps on **Authentication** page:
46+
47+
1. In **Azure Active Directory (Azure AD) authentication (preview)** section, select **Add Azure AD admins**.
48+
1. In **Select Azure AD Admins** panel, select one or more valid Azure AD user or enterprise application in the current AD tenant to be an Azure AD administrator on your Azure Cosmos DB for PostgreSQL cluster.
49+
1. Use **Select** to confirm your choice.
50+
1. In the **Authentication** page, select **Save** in the toolbar to save changes or proceed with adding native PostgreSQL roles.
51+
52+
## Configure native PostgreSQL authentication
53+
54+
To add Postgres roles on cluster, follow these steps on **Authentication** page:
55+
56+
1. In **PostgreSQL authentication** section, select **Add PostgreSQL role**.
57+
1. Enter the role name and password. Select **Save**.
58+
1. In the **Authentication** page, select **Save** in the toolbar to save changes or proceed with adding Azure Active Directory admin users.
59+
60+
The native PostgreSQL user is created on the coordinator node of the cluster, and propagated to all the worker nodes. Roles created through the Azure portal have the LOGIN attribute, which means they’re true users who can sign in to the database.
61+
62+
## Connect to Azure Cosmos for PostgreSQL by using Azure AD authentication
63+
64+
Azure AD integration works with standard PostgreSQL client tools like **psql**, which aren't Azure AD aware and support only specifying the username and password when you're connecting to PostgreSQL. In such cases, the Azure AD token is passed as the password.
65+
66+
We've tested the following clients:
67+
68+
- **psql command line**: Use the `PGPASSWORD` variable to pass the token.
69+
- **Other libpq-based clients**: Examples include common application frameworks and object-relational mappers (ORMs).
70+
- **pgAdmin**: Clear **Connect now** at server creation.
71+
72+
Use the following procedures to authenticate with Azure AD as an Azure Cosmos DB for PostgreSQL user. You can follow along in [Azure Cloud Shell](./../../cloud-shell/quickstart.md), on an Azure virtual machine, or on your local machine.
73+
74+
### Sign in to the user's Azure subscription
75+
76+
Start by authenticating with Azure AD by using the Azure CLI. This step isn't required in Azure Cloud Shell.
77+
78+
```azurecli
79+
az login
80+
```
81+
82+
The command opens a browser window to the Azure AD authentication page. It requires you to give your Azure AD user ID and password.
83+
84+
### Retrieve the Azure AD access token
85+
86+
Use the Azure CLI to acquire an access token for the Azure AD authenticated user to access Azure Cosmos for PostgreSQL. Here's an example:
87+
88+
```azurecli-interactive
89+
az account get-access-token --resource https://postgres.cosmos.azure.com
90+
```
91+
92+
After authentication is successful, Azure AD returns an access token for current Azure subscription:
93+
94+
```json
95+
{
96+
"accessToken": "[TOKEN]",
97+
"expiresOn": "[expiration_date_and_time]",
98+
"subscription": "[subscription_id]",
99+
"tenant": "[tenant_id]",
100+
"tokenType": "Bearer"
101+
}
102+
```
103+
104+
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.
105+
106+
### Use a token as a password for signing in with client psql
107+
108+
When connecting, it's best to use the access token as the PostgreSQL user password.
109+
110+
While using the psql command-line client, the access token needs to be passed through the `PGPASSWORD` environment variable. The reason is that the access token exceeds the password length that psql can accept directly.
111+
112+
Here's a Windows example:
113+
114+
```cmd
115+
set PGPASSWORD=<TOKEN value from the previous step>
116+
```
117+
118+
```powerShell
119+
$env:PGPASSWORD='<TOKEN value from from the previous step>'
120+
```
121+
122+
Here's a Linux/macOS example:
123+
124+
```bash
125+
export PGPASSWORD=<TOKEN value from the previous step>
126+
```
127+
128+
You can also combine the previous two steps together using command substitution. The token retrieval can be encapsulated into a variable and passed directly as a value for `PGPASSWORD` environment variable:
129+
130+
```bash
131+
export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --query "[accessToken]" -o tsv)
132+
```
133+
134+
135+
> [!NOTE]
136+
> Make sure PGPASSWORD variable is set to the Azure AD access token for your
137+
> subscription for Azure AD authentication. If you need to do Postgres role authentication
138+
> from the same session you can set PGPASSWORD to the Postgres role password
139+
> or clear the PGPASSWORD variable value to enter the password interactively.
140+
> Authentication would fail with the wrong value in PGPASSWORD.
141+
142+
Now you can initiate a connection with Azure Cosmos DB for PostgreSQL as you usually would (without 'password' parameter in the command line):
143+
144+
```sql
145+
psql "host=mycluster.[uniqueID].postgres.cosmos.azure.com [email protected] dbname=[db_name] sslmode=require"
146+
```
147+
148+
### Use a token as a password for signing in with PgAdmin
149+
150+
To connect by using an Azure AD token with PgAdmin, follow these steps:
151+
152+
1. Clear the **Connect now** option at server creation.
153+
1. Enter your server details on the **Connection** tab and save.
154+
1. Make sure a valid Azure AD user is specified in **Username**.
155+
1. From the pgAdmin **Object** menu, select **Connect Server**.
156+
1. Enter the Active Directory token password when you're prompted.
157+
158+
Here are some essential considerations when you're connecting:
159+
160+
- `[email protected]` is the name of the Azure AD user.
161+
- Be sure to use the exact way the Azure user is spelled. Azure AD user and group names are case-sensitive.
162+
- If the name contains spaces, use a backslash (`\`) before each space to escape it.
163+
- The access token's validity is 5 minutes to 90 minutes. You should get the access token before initiating the sign-in to Azure Cosmos for PostgreSQL.
164+
165+
You're now authenticated to your Azure Cosmos for PostgreSQL server through Azure AD authentication.
166+
167+
## Manage native PostgreSQL roles
168+
169+
When native PostgreSQL authentication is enabled on cluster, you can add and delete Postgres roles in addition to built-in 'citus' role. You can also reset password and modify Postgres privileges for native roles.
170+
171+
### How to delete a native PostgreSQL user role or change their password
172+
173+
To update a user, visit the **Authentication** page for your cluster,
174+
and select the ellipses **...** next to the user. The ellipses open a menu
175+
to delete the user or reset their password.
176+
177+
The `citus` role is privileged and can't be deleted. However, `citus` role would be disabled, if 'Azure Active Directory authentication only' authentication method is selected for the cluster.
178+
179+
## How to modify privileges for user roles
180+
181+
New user roles are commonly used to provide database access with restricted
182+
privileges. To modify user privileges, use standard PostgreSQL commands, using
183+
a tool such as PgAdmin or psql. For more information, see [Connect to a cluster](quickstart-connect-psql.md).
184+
185+
For example, to allow PostgreSQL `db_user` to read `mytable`, grant the permission:
186+
187+
```sql
188+
GRANT SELECT ON mytable TO db_user;
189+
```
190+
191+
To grant the same permissions to Azure AD role `[email protected]` use the following command:
192+
193+
```sql
194+
GRANT SELECT ON mytable TO "[email protected]";
195+
```
196+
197+
Azure Cosmos DB for PostgreSQL propagates single-table GRANT statements through the entire
198+
cluster, applying them on all worker nodes. It also propagates GRANTs that are
199+
system-wide (for example, for all tables in a schema):
200+
201+
```sql
202+
-- applies to the coordinator node and propagates to worker nodes for Postgres role db_user
203+
GRANT SELECT ON ALL TABLES IN SCHEMA public TO db_user;
204+
```
205+
206+
Or for Azure AD role
207+
208+
```sql
209+
-- applies to the coordinator node and propagates to worker nodes for Azure AD role [email protected]
210+
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "[email protected]";
211+
```
212+
213+
214+
## Next steps
215+
216+
- Learn about [authentication in Azure Cosmos DB for PostgreSQL](./concepts-authentication.md).
217+
- Review [Azure Active Directory fundamentals](./../../active-directory/fundamentals/active-directory-whatis.md).
218+
- [Learn more about SQL GRANT in PostgreSQL](https://www.postgresql.org/docs/current/sql-grant.html).

0 commit comments

Comments
 (0)