Merge pull request #88212 from jonels-msft/hyperscale-firewall

Firewall docs for hyperscale

Author: v-shils

articles/postgresql/TOC.yml

@@ -146,6 +146,12 @@
       href: concepts-hyperscale-choose-distribution-column.md
     - name: Table colocation
       href: concepts-hyperscale-colocation.md
+    - name: Data access and security
+      items:
+      - name: Firewall rules
+        href: concepts-hyperscale-firewall-rules.md
+      - name: Configure SSL
+        href: concepts-hyperscale-ssl-connection-security.md
     - name: PostgreSQL extensions
       href: concepts-hyperscale-extensions.md
     - name: Resources
@@ -240,6 +246,10 @@
     items:
     - name: Scaling
       href: howto-hyperscale-scaling.md
+    - name: Manage firewall
+      items:
+      - name: Azure portal
+        href: howto-hyperscale-manage-firewall-using-portal.md
 - name: Reference
   items:
   - name: Azure CLI

articles/postgresql/concepts-hyperscale-firewall-rules.md

@@ -0,0 +1,51 @@
+---
+title: Firewall rules in Azure Database for PostgreSQL - Hyperscale (Citus)
+description: This article describes firewall rules for Azure Database for PostgreSQL - Hyperscale (Citus).
+author: jonels-msft
+ms.author: jonels
+ms.service: postgresql
+ms.topic: conceptual
+ms.date: 9/12/2019
+---
+# Firewall rules in Azure Database for PostgreSQL - Hyperscale (Citus)
+Azure Database for PostgreSQL server firewall prevents all access to your Hyperscale (Citus) coordinator node until you specify which computers have permission. The firewall grants access to the server based on the originating IP address of each request.
+To configure your firewall, you create firewall rules that specify ranges of acceptable IP addresses. You can create firewall rules at the server level.
+
+**Firewall rules:** These rules enable clients to access your Hyperscale (Citus) coordinator node, that is, all the databases within the same logical server. Server-level firewall rules can be configured by using the Azure portal. To create server-level firewall rules, you must be the subscription owner or a subscription contributor.
+
+## Firewall overview
+All database access to your coordinator node is blocked by the firewall by default. To begin using your server from another computer, you need to specify one or more server-level firewall rules to enable access to your server. Use the firewall rules to specify which IP address ranges from the Internet to allow. Access to the Azure portal website itself is not impacted by the firewall rules.
+Connection attempts from the Internet and Azure must first pass through the firewall before they can reach your PostgreSQL Database, as shown in the following diagram:
+
+![Example flow of how the firewall works](media/concepts-hyperscale-firewall-rules/1-firewall-concept.png)
+
+## Connecting from the Internet and from Azure
+
+A Hyperscale (Citus) server group firewall controls who can connect to the group's coordinator node. The firewall determines access by consulting a configurable list of rules. Each rule is an IP address, or range of addresses, that are allowed in.
+
+When the firewall blocks connections, it can cause application errors. Using the PostgreSQL JDBC driver, for instance, raises an error like this:
+
+> java.util.concurrent.ExecutionException: java.lang.RuntimeException:
+> org.postgresql.util.PSQLException: FATAL: no pg\_hba.conf entry for host "123.45.67.890", user "citus", database "citus", SSL
+
+See [Create and manage firewall rules](howto-hyperscale-manage-firewall-using-portal.md) to learn how the rules are defined.
+
+## Troubleshooting the database server firewall
+When access to the Microsoft Azure Database for PostgreSQL - Hyperscale (Citus) service doesn't behave as you expect, consider these points:
+
+* **Changes to the allow list have not taken effect yet:** There may be as much as a five-minute delay for changes to the Hyperscale (Citus) firewall configuration to take effect.
+
+* **The user is not authorized or an incorrect password was used:** If a user does not have permissions on the server or the password used is incorrect, the connection to the server is denied. Creating a firewall setting only provides clients with an opportunity to attempt connecting to your server; each client must still provide the necessary security credentials.
+
+For example, using a JDBC client, the following error may appear.
+> java.util.concurrent.ExecutionException: java.lang.RuntimeException: org.postgresql.util.PSQLException: FATAL: password authentication failed for user "yourusername"
+
+* **Dynamic IP address:** If you have an Internet connection with dynamic IP addressing and you are having trouble getting through the firewall, you could try one of the following solutions:
+
+* Ask your Internet Service Provider (ISP) for the IP address range assigned to your client computers that access the Hyperscale (Citus) coordinator node, and then add the IP address range as a firewall rule.
+
+* Get static IP addressing instead for your client computers, and then add the static IP address as a firewall rule.
+
+## Next steps
+For articles on creating server-level and database-level firewall rules, see:
+* [Create and manage Azure Database for PostgreSQL firewall rules using the Azure portal](howto-hyperscale-manage-firewall-using-portal.md)

articles/postgresql/concepts-hyperscale-ssl-connection-security.md

@@ -0,0 +1,35 @@
+---
+title: Configure SSL in Azure Database for PostgreSQL - Hyperscale (Citus)
+description: Instructions and information to configure Azure Database for PostgreSQL - Hyperscale (Citus) and associated applications to properly use SSL connections.
+author: jonels-msft
+ms.author: jonels
+ms.service: postgresql
+ms.topic: conceptual
+ms.date: 09/17/2019
+---
+# Configure SSL in Azure Database for PostgreSQL - Hyperscale (Citus)
+Client application connections to the Hyperscale (Citus) coordinator node require Secure Sockets Layer (SSL). Enforcing SSL connections between your database server and your client applications helps protect against "man-in-the-middle" attacks by encrypting the data stream between the server and your application.
+
+## Enforcing SSL connections
+For all Azure Database for PostgreSQL servers provisioned through the Azure portal, enforcement of SSL connections is enabled by default. 
+
+Likewise, connection strings that are pre-defined in the "Connection Strings" settings under your server in the Azure portal include the required parameters for common languages to connect to your database server using SSL. The SSL parameter varies based on the connector, for example "ssl=true" or "sslmode=require" or "sslmode=required" and other variations.
+
+## Ensure your application or framework supports SSL connections
+Some application frameworks that use PostgreSQL for their database services do not enable SSL by default during installation. If your PostgreSQL server enforces SSL connections but the application is not configured for SSL, the application may fail to connect to your database server. Consult your application's documentation to learn how to enable SSL connections.
+
+## Applications that require certificate verification for SSL connectivity
+In some cases, applications require a local certificate file generated from a trusted Certificate Authority (CA) certificate file (.cer) to connect securely. The certificate to connect to an Azure Database for PostgreSQL - Hyperscale (Citus) is located at https://dl.cacerts.digicert.com/DigiCertGlobalRootCA.crt.pem. Download the certificate file and save it to your preferred location.
+
+### Connect using psql
+The following example shows how to connect to your Hyperscale (Citus) coordinator node using the psql command-line utility. Use the `sslmode=verify-full` connection string setting to enforce SSL certificate verification. Pass the local certificate file path to the `sslrootcert` parameter.
+
+Below is an example of the psql connection string:
+```
+psql "sslmode=verify-full sslrootcert=DigiCertGlobalRootCA.crt.pem host=mydemoserver.postgres.database.azure.com dbname=citus user=citus password=your_pass"
+```
+> [!TIP]
+> Confirm that the value passed to `sslrootcert` matches the file path for the certificate you saved.
+
+## Next steps
+Increase security further with [Firewall rules in Azure Database for PostgreSQL - Hyperscale (Citus)](concepts-hyperscale-firewall-rules.md).

articles/postgresql/howto-hyperscale-manage-firewall-using-portal.md

@@ -0,0 +1,57 @@
+---
+title: Manage firewall rules in Azure Database for PostgreSQL - Hyperscale (Citus)
+description: Create and manage firewall rules for Azure Database for PostgreSQL - Hyperscale (Citus) using the Azure portal
+author: jonels-msft
+ms.author: jonels
+ms.service: postgresql
+ms.topic: conceptual
+ms.date: 9/12/2019
+---
+# Manage firewall rules for Azure Database for PostgreSQL - Hyperscale (Citus)
+Server-level firewall rules can be used to manage access to a Hyperscale (Citus) coordinator node from a specified IP address or range of IP addresses.
+
+## Prerequisites
+To step through this how-to guide, you need:
+- A server group [Create an Azure Database for PostgreSQL – Hyperscale (Citus) server group](quickstart-create-hyperscale-portal.md).
+
+## Create a server-level firewall rule in the Azure portal
+
+> [!NOTE]
+> These settings are also accessible during the creation of an Azure Database for PostgreSQL - Hyperscale (Citus) server group. Under the **Networking** tab, click **Public endpoint**.
+> ![Azure portal - networking tab](./media/howto-hyperscale-manage-firewall-using-portal/0-create-public-access.png)
+
+1. On the PostgreSQL server group page, under the Security heading, click **Networking** to open the Firewall rules.
+
+   ![Azure portal - click Networking](./media/howto-hyperscale-manage-firewall-using-portal/1-connection-security.png)
+
+2. Click **Add client IP**, either on the toolbar (option A below), or in the link (option B). Either way automatically creates a firewall rule with the public IP address of your computer, as perceived by the Azure system.
+
+   ![Azure portal - click Add client IP](./media/howto-hyperscale-manage-firewall-using-portal/2-add-my-ip.png)
+
+Alternately, clicking **+Add 0.0.0.0 - 255.255.255.255** (to the right of option B) allows not just your IP, but the whole internet to access the coordinator node's port 5432. In this situation, clients still must login with the correct username and password to use the cluster. Nevertheless, we recommend allowing worldwide access for only short periods of time and for only non-production databases.
+
+3. Verify your IP address before saving the configuration. In some situations, the IP address observed by Azure portal differs from the IP address used when accessing the internet and Azure servers. Therefore, you may need to change the Start IP and End IP to make the rule function as expected.
+   Use a search engine or other online tool to check your own IP address. For example, search for "what is my IP."
+
+   ![Bing search for What is my IP](./media/howto-hyperscale-manage-firewall-using-portal/3-what-is-my-ip.png)
+
+4. Add additional address ranges. In the firewall rules, you can specify a single IP address or a range of addresses. If you want to limit the rule to a single IP address, type the same address in the field for Start IP and End IP. Opening the firewall enables administrators, users, and applications to access the coordinator node on port 5432.
+
+5. Click **Save** on the toolbar to save this server-level firewall rule. Wait for the confirmation that the update to the firewall rules was successful.
+
+## Connecting from Azure
+
+There is an easy way to grant Hyperscale database access to applications hosted on Azure (such as an Azure Web Apps application, or those running in an Azure VM). Simply set the **Allow Azure services and resources to access this server group** option to **Yes** in the portal from the **Networking** pane and hit **Save**.
+
+> [!IMPORTANT]
+> This option configures the firewall to allow all connections from Azure including connections from the subscriptions of other customers. When selecting this option, make sure your login and user permissions limit access to only authorized users.
+
+## Manage existing server-level firewall rules through the Azure portal
+Repeat the steps to manage the firewall rules.
+* To add the current computer, click the button to + **Add client IP**. Click **Save** to save the changes.
+* To add additional IP addresses, type in the Rule Name, Start IP Address, and End IP Address. Click **Save** to save the changes.
+* To modify an existing rule, click any of the fields in the rule and modify. Click **Save** to save the changes.
+* To delete an existing rule, click the ellipsis […] and click **Delete** to remove the rule. Click **Save** to save the changes.
+
+## Next steps
+- Learn more about [Concept of firewall rules](concepts-hyperscale-firewall-rules.md), including how to troubleshoot connection problems.