Merge pull request #224322 from markingmyname/pgaad

[PostgreSQL]  Update AAD article

Author: American-Dipper

articles/postgresql/flexible-server/how-to-configure-sign-in-azure-ad-authentication.md

@@ -4,7 +4,7 @@ description: Learn how to set up Azure Active Directory (Azure AD) for authentic
 author: kabharati
 ms.author: kabharati
 ms.reviewer: maghan
-ms.date: 11/04/2022
+ms.date: 01/18/2023
 ms.service: postgresql
 ms.subservice: flexible-server
 ms.topic: how-to
@@ -19,14 +19,14 @@ In this article, you'll configure Azure Active Directory (Azure AD) access for a
 > [!NOTE]  
 > Azure Active Directory authentication for Azure Database for PostgreSQL - Flexible Server is currently in preview.
 
-You can configure Azure AD authentication for Azure Database for PostgreSQL - Flexible Server either during server provisioning or later. Only Azure AD administrator users can create or enable users for Azure AD-based authentication. We recommend not using the Azure AD administrator for regular database operations, because that role has elevated user permissions (for example, CREATEDB). 
+You can configure Azure AD authentication for Azure Database for PostgreSQL - Flexible Server either during server provisioning or later. Only Azure AD administrator users can create or enable users for Azure AD-based authentication. We recommend not using the Azure AD administrator for regular database operations because that role has elevated user permissions (for example, CREATEDB).
 
-You can have multiple Azure AD admin users with Azure Database for PostgreSQL - Flexible Server. Azure AD admin users can be a user, a group, or a service principal.
+You can have multiple Azure AD admin users with Azure Database for PostgreSQL - Flexible Server. Azure AD admin users can be a user, a group, or service principal.
 
 ## Prerequisites
 
 - An Azure account with an active subscription. If you don't already have one, [create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
-- One of the following roles: Global Administrator, Privileged Role Administrator, Tenant Administrator.
+- One of the following roles: **Global Administrator**, **Privileged Role Administrator**, **Tenant Creator**.
 - Installation of the [Azure CLI](/cli/azure/install-azure-cli).
 
 ## Install the Azure AD PowerShell module
@@ -38,28 +38,38 @@ The following steps are mandatory to use Azure AD authentication with Azure Data
 ```powershell
 Connect-AzureAD -TenantId <customer tenant id>
 ```
-A successful output will look similar to the following.
 
-```
-Account                       Environment TenantId                             TenantDomain                       AccountType
--------                       ----------- --------                             ------------                       -----------
-[email protected] AzureCloud  456e5515-431d-4a70-874d-bdae2ba97c1d <your tenant name>.onmicrosoft.com User
-```
+A successful output looks similar to the following.
 
-Ensure that your Azure tenant has the service principal for the Azure Database for PostgreSQL Flexible Server. This only needs to be done once per Azure tenant. First, check for the existence of the service principal in your tenant with this command. The specific ObjectId value is for the Azure Database for PostgreSQL Flexible Server service principal.
+```output
+Account          Environment TenantId          TenantDomain                       AccountType
+-------          ----------- --------          ------------                       -----------
+<your account>   AzureCloud  <your tenant Id>  <your tenant name>.onmicrosoft.com    User
 ```
-Get-AzureADServicePrincipal -ObjectId 0049e2e2-fcea-4bc4-af90-bdb29a9bbe98
+
+Ensure that your Azure tenant has the service principal for the Azure Database for PostgreSQL Flexible Server. This only needs to be done once per Azure tenant. First, check for the existence of the service principal in your tenant with this command. The ObjectId value is for the Azure Database for PostgreSQL Flexible Server service principal.
+
+> [!NOTE]  
+> The following script is an example of a created Azure App Registration you can use for testing. If you want to apply your ids, you need to use your own App Registration object and application id.
+
+```powershell
+Get-AzureADServicePrincipal -ObjectId 97deb67a-332c-456a-9ef4-3a95eb59c74b
 ```
+
 If the service principal exists, you'll see the following output.
-```
+
+```output
 ObjectId                             AppId                                DisplayName
 --------                             -----                                -----------
 0049e2e2-fcea-4bc4-af90-bdb29a9bbe98 5657e26c-cc92-45d9-bc47-9da6cfdb4ed9 Azure OSSRDBMS PostgreSQL Flexible Server
 ```
 
+> [!IMPORTANT]  
+> If you are not a **Global Administrator**, **Privileged Role Administrator**, **Tenant Creator** you can't proceed past this step.
+
 ### Grant read access
 
-Grant Azure Database for PostgreSQL - Flexible Server Service Principal read access to a customer tenant, to request Graph API tokens for Azure AD validation tasks:
+Grant Azure Database for PostgreSQL - Flexible Server Service Principal read access to a customer tenant to request Graph API tokens for Azure AD validation tasks:
 
 ```powershell
 New-AzureADServicePrincipal -AppId 5657e26c-cc92-45d9-bc47-9da6cfdb4ed9
@@ -74,20 +84,22 @@ Azure AD is a multitenant application. It requires outbound connectivity to perf
 - **Public access (allowed IP addresses)**: No extra network rules are required.
 - **Private access (virtual network integration)**:
 
-  - You need an outbound network security group (NSG) rule to allow virtual network traffic to reach the `AzureActiveDirectory` service tag only.
-  - Optionally, if you're using a proxy, you can add a new firewall rule to allow HTTP/S traffic to reach the `AzureActiveDirectory` service tag only.
+  - You need an outbound network security group (NSG) rule to allow virtual network traffic to only reach the `AzureActiveDirectory` service tag.
+  - Optionally, if you're using a proxy, you can add a new firewall rule to allow HTTP/S traffic to reach only the `AzureActiveDirectory` service tag.
 
 To set the Azure AD admin during server provisioning, follow these steps:
 
 1. In the Azure portal, during server provisioning, select either **PostgreSQL and Azure Active Directory authentication** or **Azure Active Directory authentication only** as the authentication method.
 1. On the **Set admin** tab, select a valid Azure AD user, group, service principal, or managed identity in the customer tenant to be the Azure AD administrator.
- 
-   You can optionally add a local PostgreSQL admin account if you prefer using the **PostgreSQL and Azure Active Directory authentication** method.
 
-   > [!NOTE]
-   > You can add only one Azure admin user during server provisioning. You can add multiple Azure AD admin users after the server is created.
+  You can optionally add a local PostgreSQL admin account if you prefer using the **PostgreSQL and Azure Active Directory authentication** method.
+
+  > [!NOTE]  
+  > You can add only one Azure admin user during server provisioning. You can add multiple Azure AD admin users after the Server is created.
+
+
+  :::image type="content" source="media/how-to-configure-sign-in-Azure-ad-authentication/set-Azure-ad-admin-server-creation.png" alt-text="Screenshot that shows selections for setting an Azure AD admin during server provisioning.]":::
 
-![Screenshot that shows selections for setting an Azure AD admin during server provisioning.][3]
 
 To set the Azure AD administrator after server creation, follow these steps:
 
@@ -96,18 +108,18 @@ To set the Azure AD administrator after server creation, follow these steps:
 1. Select **Add Azure AD Admins**. Then select a valid Azure AD user, group, service principal, or managed identity in the customer tenant to be an Azure AD administrator.
 1. Select **Save**.
 
-![Screenshot that shows selections for setting an Azure AD admin after server creation.][2]
+  :::image type="content" source="media/how-to-configure-sign-in-Azure-ad-authentication/set-Azure-ad-admin.png" alt-text="Screenshot that shows selections for setting an Azure AD admin after server creation.":::
 
 > [!IMPORTANT]  
-> When you're setting the administrator, a new user is added to Azure Database for PostgreSQL - Flexible Server with full administrator permissions.
+> When setting the administrator, a new user is added to Azure Database for PostgreSQL - Flexible Server with full administrator permissions.
 
 ## Connect to Azure Database for PostgreSQL by using Azure AD
 
 The following high-level diagram summarizes the workflow of using Azure AD authentication with Azure Database for PostgreSQL:
 
-![Diagram of authentication flow between Azure Active Directory, the user's computer, and the server.][1]
+  :::image type="content" source="media/how-to-configure-sign-in-Azure-ad-authentication/authentication-flow.png" alt-text="Diagram of authentication flow between Azure Active Directory, the user's computer, and the server.":::
 
-Azure AD integration works with standard PostgreSQL tools like psql, which aren't Azure AD aware and support only specifying the username and password when you're connecting to PostgreSQL. The Azure AD token is passed as the password, as shown in the preceding diagram.
+Azure AD integration works with standard PostgreSQL tools like psql, which aren't Azure AD aware and support only specifying the username and password when you're connecting to PostgreSQL. As shown in the preceding diagram, the Azure AD token is passed as the password.
 
 We've tested the following clients:
 
@@ -118,7 +130,7 @@ We've tested the following clients:
 
 ## Authenticate with Azure AD
 
-Use the following procedures to authenticate with Azure AD as an Azure Database for PostgreSQL - Flexible Server user. You can follow along in Azure Cloud Shell, on an Azure virtual machine, or on your local machine. 
+Use the following procedures to authenticate with Azure AD as an Azure Database for PostgreSQL - Flexible Server user. You can follow along in Azure Cloud Shell, on an Azure virtual machine, or on your local machine.
 
 ### Sign in to the user's Azure subscription
 
@@ -132,7 +144,7 @@ The command opens a browser window to the Azure AD authentication page. It requi
 
 ### Retrieve the Azure AD access token
 
-Use the Azure CLI to acquire an access token for the Azure AD authenticated user to access Azure Database for PostgreSQL. Here's an example for the public cloud:
+Use the Azure CLI to acquire an access token for the Azure AD authenticated user to access Azure Database for PostgreSQL. Here's an example of the public cloud:
 
 ```azurecli-interactive
 az account get-access-token --resource https://ossrdbms-aad.database.windows.net
@@ -166,9 +178,9 @@ The token is a Base64 string. It encodes all the information about the authentic
 
 ### Use a token as a password for signing in with client psql
 
-When you're connecting, it's best to use the access token as the PostgreSQL user password.
+When connecting, it's best to use the access token as the PostgreSQL user password.
 
-While you're 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.
+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.
 
 Here's a Windows example:
 
@@ -182,20 +194,19 @@ $env:PGPASSWORD='<copy/pasted TOKEN value from step 2>'
 
 Here's a Linux/macOS example:
 
-```shell
+```bash
 export PGPASSWORD=<copy/pasted TOKEN value from step 2>
 ```
 
 You can also combine step 2 and step 3 together using command substitution. The token retrieval can be encapsulated into a variable and passed directly as a value for `PGPASSWORD` environment variable:
 
-```shell
+```bash
 export PGPASSWORD=$(az account get-access-token --resource-type oss-rdbms --query "[accessToken]" -o tsv)
 ```
 
+Now you can initiate a connection with Azure Database for PostgreSQL as you usually would:
 
-Now you can initiate a connection with Azure Database for PostgreSQL as you normally would:
-
-```shell
+```sql
 psql "host=mydb.postgres... [email protected] dbname=postgres sslmode=require"
 ```
 
@@ -210,24 +221,24 @@ To connect by using an Azure AD token with PgAdmin, follow these steps:
 
 Here are some essential considerations when you're connecting:
 
-* `[email protected]` is the name of the Azure AD user.
-* Be sure to use the exact way that the Azure user is spelled. Azure AD user and group names are case-sensitive.
-* If the name contains spaces, use a backslash (`\`) before each space to escape it.
-* The access token's validity is 5 minutes to 60 minutes. We recommend that you get the access token just before you initiate the sign-in to Azure Database for PostgreSQL.
+- `[email protected]` is the name of the Azure AD user.
+- Be sure to use the exact way the Azure user is spelled. Azure AD user and group names are case-sensitive.
+- If the name contains spaces, use a backslash (`\`) before each space to escape it.
+- The access token's validity is 5 minutes to 60 minutes. You should get the access token before initiating the sign-in to Azure Database for PostgreSQL.
 
 You're now authenticated to your Azure Database for PostgreSQL server through Azure AD authentication.
 
 ## Authenticate with Azure AD as a group member
 
 ### Create Azure AD groups in Azure Database for PostgreSQL - Flexible Server
 
-To enable an Azure AD group for access to your database, use the same mechanism that you used for users, but instead specify the group name. For example:
+To enable an Azure AD group to access your database, use the same mechanism you used for users, but specify the group name instead. For example:
 
-```
+```sql
 select * from pgAzure ADauth_create_principal('Prod DB Readonly', false, false).
 ```
 
-When group members sign in, they use their personal access tokens but specify the group name as the username.
+When group members sign in, they use their access tokens but specify the group name as the username.
 
 > [!NOTE]  
 > Azure Database for PostgreSQL - Flexible Server supports managed identities as group members.
@@ -236,19 +247,19 @@ When group members sign in, they use their personal access tokens but specify th
 
 Authenticate with Azure AD by using the Azure CLI. This step isn't required in Azure Cloud Shell. The user needs to be a member of the Azure AD group.
 
-```
+```azurecli-interactive
 az login
 ```
 
 ### Retrieve the Azure AD access token
 
-Use the Azure CLI to acquire an access token for the Azure AD authenticated user to access Azure Database for PostgreSQL. Here's an example for the public cloud:
+Use the Azure CLI to acquire an access token for the Azure AD authenticated user to access Azure Database for PostgreSQL. Here's an example of the public cloud:
 
 ```azurecli-interactive
 az account get-access-token --resource https://ossrdbms-aad.database.windows.net
 ```
 
-You must specify the preceding resource value exactly as shown. For other clouds, you can look up the resource value by using the following command:
+You must specify the initial resource value exactly as shown. For other clouds, you can look up the resource value by using the following command:
 
 ```azurecli-interactive
 az cloud show
@@ -274,23 +285,17 @@ After authentication is successful, Azure AD returns an access token:
 
 ### Use a token as a password for signing in with psql or PgAdmin
 
-These considerations are important when you're connecting as a group member:
+These considerations are essential when you're connecting as a group member:
 
-- The group name is the name of the Azure AD group that you're trying to connect as.
-- Be sure to use the exact way that the Azure AD group name is spelled. Azure AD user and group names are case-sensitive.
+- The group name is the name of the Azure AD group that you're trying to connect.
+- Be sure to use the exact way the Azure AD group name is spelled. Azure AD user and group names are case-sensitive.
 - When you're connecting as a group, use only the group name and not the alias of a group member.
 - If the name contains spaces, use a backslash (`\`) before each space to escape it.
-- The access token's validity is 5 minutes to 60 minutes. We recommend that you get the access token just before you initiate the sign-in to Azure Database for PostgreSQL.
+- The access token's validity is 5 minutes to 60 minutes. We recommend you get the access token before initiating the sign-in to Azure Database for PostgreSQL.
 
 You're now authenticated to your PostgreSQL server through Azure AD authentication.
 
 ## Next steps
 
 - Review the overall concepts for [Azure AD authentication with Azure Database for PostgreSQL - Flexible Server](concepts-azure-ad-authentication.md).
-- Learn how to [Manage Azure Active Directory users - Azure Database for PostgreSQL - Flexible Server](how-to-manage-azure-ad-users.md).
-
-<!--Image references-->
-
-[1]: ./media/concepts-azure-ad-authentication/authentication-flow.png
-[2]: ./media/concepts-azure-ad-authentication/set-azure-ad-admin.png
-[3]: ./media/concepts-azure-ad-authentication/set-azure-ad-admin-server-creation.png
+- Learn how to [Manage Azure Active Directory users - Azure Database for PostgreSQL - Flexible Server](how-to-manage-azure-ad-users.md).