Add guide for Azure Postgres/MySQL database access (#9729)

docs/config.json

@@ -187,6 +187,7 @@
             { "title": "AWS Redshift", "slug": "/database-access/guides/postgres-redshift/" },
             { "title": "GCP Cloud SQL PostgreSQL", "slug": "/database-access/guides/postgres-cloudsql/" },
             { "title": "GCP Cloud SQL MySQL", "slug": "/database-access/guides/mysql-cloudsql/" },
+            { "title": "Azure PostgreSQL & MySQL", "slug": "/database-access/guides/azure-postgres-mysql/" },
             { "title": "MongoDB Atlas", "slug": "/database-access/guides/mongodb-atlas/" },
             { "title": "Self-Hosted PostgreSQL", "slug": "/database-access/guides/postgres-self-hosted/" },
             { "title": "Self-Hosted MySQL/MariaDB", "slug": "/database-access/guides/mysql-self-hosted/" },

docs/pages/database-access/guides.mdx

@@ -21,6 +21,9 @@ layout: tocless-doc
   <Tile icon="cloud" title="GCP Cloud SQL MySQL" href="./guides/mysql-cloudsql.mdx">
     Connect GCP Cloud SQL MySQL database.
   </Tile>
+  <Tile icon="cloud" title="Azure PostgreSQL & MySQL" href="./guides/azure-postgres-mysql.mdx">
+    Connect Azure PostgreSQL or MySQL.
+  </Tile>
   <Tile icon="cloud" title="MongoDB Atlas" href="./guides/mongodb-atlas.mdx">
     Connect MongoDB Atlas cluster.
   </Tile>

docs/pages/database-access/guides/azure-postgres-mysql.mdx

@@ -0,0 +1,270 @@
+---
+title: Database Access with Azure PostgreSQL and MySQL
+description: How to configure Teleport Database Access with Azure Database for PostgreSQL and MySQL.
+---
+
+<Details
+  title="Version warning"
+  opened={true}
+  scope={["oss", "enterprise"]}
+  scopeOnly={true}
+  min="8.1"
+>
+  Database access for Azure PostgreSQL/MySQL is available starting from Teleport
+  `8.1`.
+</Details>
+
+This guide will help you to:
+
+- Install and configure Teleport.
+- Set up access to Azure Database for PostgreSQL or Azure Database for MySQL.
+- Connect to the database server through Teleport.
+
+<Admonition type="note">
+    Teleport uses Azure Active Directory authentication with Azure PostgreSQL
+    and MySQL databases which at the moment of this writing is only supported
+    by Single Server. Flexible Server does not support Azure AD authentication.
+</Admonition>
+
+## Prerequisites
+
+- Teleport version >= `8.1`.
+- Deployed Azure Database for PostgreSQL or MySQL server.
+- Azure Active Directory administrative privileges.
+
+## Step 1/4. Install and configure Teleport
+
+### Set up Teleport Auth and Proxy Services
+
+(!docs/pages/includes/database-access/start-auth-proxy.mdx!)
+
+### Set up Teleport Database Service
+
+(!docs/pages/includes/database-access/token.mdx!)
+
+Start Teleport Database Service. Make sure to update `--auth-server` to point to
+your Teleport Proxy Service address and `--uri` to the Azure database server
+endpoint.
+
+<Tabs>
+<TabItem label="PostgreSQL">
+  ```bash
+  $ teleport db start \
+    --token=/tmp/token \
+    --auth-server=teleport.example.com:3080 \
+    --name=azure-db \
+    --protocol=postgres \
+    --uri=example.postgres.database.azure.com:5321 \
+    --labels=env=dev
+  ```
+</TabItem>
+<TabItem label="MySQL">
+  ```bash
+  $ teleport db start \
+    --token=/tmp/token \
+    --auth-server=teleport.example.com:3080 \
+    --name=azure-db \
+    --protocol=mysql \
+    --uri=example.mysql.database.azure.com:3306 \
+    --labels=env=dev
+  ```
+</TabItem>
+</Tabs>
+
+<Admonition type="tip">
+  You can start Teleport Database Service using a configuration file instead of
+  CLI flags. See [YAML reference](../reference/configuration.mdx).
+</Admonition>
+
+### Create Teleport user
+
+(!docs/pages/includes/database-access/create-user.mdx!)
+
+## Step 2/4. Configure Azure service principal
+
+To authenticate with PostgreSQL or MySQL databases, Teleport Database Service
+needs to obtain access tokens from Azure AD. There are a couple of ways to
+achieve that:
+
+- Database Service can be registered as an Azure AD application (via AD's "App
+  registrations") and configured with its credentials. This is only recommended
+  for development and testing purposes since it requires Azure credentials to
+  be present in the Database Service's environment.
+- Database Service can run on an Azure VM with attached managed identity. This
+  is the recommended way of deploying the Database Service in production since
+  it eliminates the need to manage Azure credentials.
+
+<Tabs>
+<TabItem label="Using managed identity">
+  Go to the [Managed Identities](https://portal.azure.com/#blade/HubsExtension/BrowseResource/resourceType/Microsoft.ManagedIdentity%2FuserAssignedIdentities)
+  page in your Azure portal and click _Create_ to create a new user-assigned
+  managed identity:
+
+  ![Managed identities](../../../img/database-access/guides/azure/[email protected])
+
+  Pick a name and resource group for the new identity and create it:
+
+  ![New identity](../../../img/database-access/guides/azure/[email protected])
+
+  Take note of the created identity's _Client ID_:
+
+  ![Created identity](../../../img/database-access/guides/azure/[email protected])
+
+  Next, navigate to the Azure VM that will run your Database Service agent and
+  add the identity you've just created to it:
+
+  ![VM identity](../../../img/database-access/guides/azure/[email protected])
+
+  Attach this identity to all Azure VMs that will be running the Database
+  Service.
+</TabItem>
+<TabItem label="Using app registrations">
+  <Admonition type="note">
+    Registering the Database Service as Azure AD application is suitable for
+    test and development scenarios, or if your Database Service does not run on
+    an Azure VM. For production scenarios prefer to use the managed identity
+    approach.
+  </Admonition>
+
+  Go the the [App registrations](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps)
+  page of your Azure Active Directory and click on *New registration*:
+
+  ![App registrations](../../../img/database-access/guides/azure/[email protected])
+
+  Pick a name (e.g. _DatabaseService_) and register a new application. Once the
+  app has been created, take note of its _Application (client) ID_ and click on
+  *Add a certificate or secret*:
+
+  ![Registered app](../../../img/database-access/guides/azure/[email protected])
+
+  Create a new client secret that the Database Service agent will use to
+  authenticate with the Azure API:
+
+  ![Registered app secrets](../../../img/database-access/guides/azure/[email protected])
+
+  Teleport Database Service uses Azure SDK's default credential provider chain to
+  look for credentials. Refer to [Authentication methods](https://docs.microsoft.com/en-us/azure/developer/go/azure-sdk-authorization)
+  to pick a method suitable for your use-case. For example, to use
+  environment-based authentication with a client secret, Database Service should
+  have the following environment variables set:
+
+  ```bash
+  export AZURE_TENANT_ID=
+  export AZURE_CLIENT_ID=
+  export AZURE_CLIENT_SECRET=
+  ```
+</TabItem>
+</Tabs>
+
+## Step 3/4. Create Azure database users
+
+To let Teleport connect to your Azure database authenticating as a service
+principal you need to create Azure AD users for that principal in the database.
+
+### Assign Azure AD administrator
+
+Only the Azure AD administrator for the database can connect to it and create
+Azure AD users. Go to your database's _Active Directory admin_ page
+and set the AD admin using the _Set admin_ button:
+
+![Set AD admin](../../../img/database-access/guides/azure/[email protected])
+
+Note that only one AD user can be set as an admin for the database.
+
+### Connect to the database as an AD admin
+
+Next, you need to connect to your database as the AD admin user.
+
+Use the Azure `az` CLI utility to log in as the user that you set as the AD admin,
+fetch the access token and use it as a password when connecting to the database:
+
+<Tabs>
+<TabItem label="PostgreSQL">
+  ```bash
+  $ az login -u [email protected]
+  $ export PGPASSWORD=`az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken`
+  $ psql "host=example.postgres.database.azure.com [email protected]@instance-name sslmode=require dbname=postgres"
+  ```
+</TabItem>
+<TabItem label="MySQL">
+  ```bash
+  $ az login -u [email protected]
+  $ export TOKEN=`az account get-access-token --resource-type oss-rdbms --output tsv --query accessToken`
+  $ mysql -h example.mysql.database.azure.com -P 3306 -u [email protected]@instance-name --enable-cleartext-plugin --password=$TOKEN
+  ```
+</TabItem>
+</Tabs>
+
+Note that the database username must include `@instance-name` suffix with the
+name of the Azure database instance you're connecting to.
+
+### Create AD users
+
+Once connected to the database as AD admin, create database users for the
+service principal that Teleport Database Service will be using. Use `Client ID`
+when using managed identities and `Application (client) ID` when using app
+registrations:
+
+<Tabs>
+<TabItem label="PostgreSQL">
+  ```
+  postgres=> SET aad_validate_oids_in_tenant = off;
+  SET
+  postgres=> CREATE ROLE teleport WITH LOGIN PASSWORD '11111111-2222-3333-4444-555555555555' IN ROLE azure_ad_user;
+  CREATE ROLE
+  ```
+</TabItem>
+<TabItem label="MySQL">
+  ```
+  mysql> SET aad_auth_validate_oids_in_tenant = OFF;
+  mysql> CREATE AADUSER 'teleport' IDENTIFIED BY '11111111-2222-3333-4444-555555555555';
+  Query OK, 0 rows affected (0.92 sec)
+  ```
+</TabItem>
+</Tabs>
+
+You can create multiple database users for the same service principal.
+
+## Step 4/4. Connect
+
+Log into your Teleport cluster. Your Azure database should appear in the list of
+available databases:
+
+```code
+$ tsh login --proxy=teleport.example.com --user=alice
+$ tsh db ls
+# Name     Description         Labels
+# -------- ------------------- -------
+# azure-db                     env=dev
+```
+
+Fetch short-lived client certificate for it using `tsh db login` command:
+
+```code
+$ tsh db login --db-user=teleport azure-db
+```
+
+<Admonition type="tip">
+  You can be logged into multiple databases simultaneously.
+</Admonition>
+
+Now connect to the database:
+
+```code
+$ tsh db connect azure-db
+```
+
+<Admonition type="note">
+  The appropriate database command-line client (`psql`, `mysql`) should be
+  available in PATH of the machine you're running `tsh db connect` from.
+</Admonition>
+
+To log out of the database and remove credentials:
+
+```code
+$ tsh db logout azure-db
+```
+
+## Next steps
+
+(!docs/pages/includes/database-access/guides-next-steps.mdx!)

docs/pages/database-access/introduction.mdx

@@ -64,6 +64,9 @@ with Github, execute a few SQL queries and observe them in the audit log:
   <Tile icon="cloud" title="GCP Cloud SQL MySQL" href="./guides/mysql-cloudsql.mdx">
     Connect GCP Cloud SQL MySQL database.
   </Tile>
+  <Tile icon="cloud" title="Azure PostgreSQL & MySQL" href="./guides/azure-postgres-mysql.mdx">
+    Connect Azure PostgreSQL or MySQL.
+  </Tile>
   <Tile icon="cloud" title="MongoDB Atlas" href="./guides/mongodb-atlas.mdx">
     Connect MongoDB Atlas cluster.
   </Tile>